• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• Command Line Options:
• Configuration File Options
• EXAMPLES
• VERSION
• AUTHOR
• COPYRIGHT

NAME

servertest.pl - log response times for a list of URLs over time

SYNOPSIS

servertest.pl --help
   --interactive --pause=yes/no
   --config_file=filename --logfile=filename
   --agent "agent string" --timeout=seconds
   --maxpolls=n --pollfrequency=seconds
   --restart=yes/no
   --test=URL --test_agent=URL "agent string"
   URL1 URL2 ... URLn

DESCRIPTION

This program sends periodic HTTP GET requests to one or more URLs in order to get an indication of the average response time and pattern of timeouts for each. The results of each poll are printed on STDOUT, and optionally logged to a text logfile.

If a logfile is used, then each time the program is run it can "restart" by first processing the logfile so as to continue to accumulate statistics calculated with running totals.

The output consists of lines in one of the following forms:

   n date time url fetchtime average (max) timeout-info

or:

   n date time url FAILED: status line

For example:

  33 2004-01-27 19:30:23  www.dom314.com  1  0.8 (30) 
  33 2004-01-27 19:30:24  www.dom314.net FAILED: 500 read timeout

  34 2004-01-27 19:45:26  www.dom314.com  0  0.8 (30) 
  34 2004-01-27 19:45:26  www.dom314.net  1  0.6 (10) 4 timeouts (1.3%)

The fields are defined as follows:

n

The sequence number of the poll. Each poll consists of making HTTP GET requests to each of the URLs listed for test in turn, in the order defined. If more than one URL is being tested, then there will be multiple lines with the same sequence number. If the program is run with "restart" not set to "no", then before the first poll it will read the logfile, if present, to find the highest sequence number and start counting after that.

date time

The date and time of the request, local to the computer running the program.

url

The URL being tested. This value is right justified with spaces to help the numbers following it line up for easy reading.

fetchtime

The number of seconds taken to receive a successful response to the request. This is an integer.

average

The average time for a response to all of the polls for this URL in this sequence. Calculated by dividing the total time for all successful responses by the number of successful responses for this URL.

Note that the number of polls to this URL may not correspond to the sequence number of the poll because this program may be restarted to add to an existing log but with a changed set of URLs to test.

max

The maximum time taken for a response in this sequence for this URL.

timeout-info

If there have been any failed requested for this URL, the total number of "timeouts" are listed, along with a percentage calculated by dividing the number of timeouts by the sum of the total successful requests and the total timeouts.

FAILED: status line

If the request fails for any reason, including a timeout or other error, then the word "FAILED:" is logged followed by the status information returned by the system, usually both as a number and some text.

OPTIONS

Options to this program may be set through command line options, interactive prompting and responses on the terminal, or the use of a configuration file. The command line options are processed in order. If an option that specifies interactive processing is encountered, then prompts are displayed and input will be awaited at that point in the processing of the command line options. If an option that specifies a configuration file is encountered, then that file is processed at that point, with processing then continued of the command line options. This lets you override configuration file values by specifying them after the configuration file on the command line or interactively.

If no options are given on the command line, then interactive processing is assumed.

Command Line Options:

--agent "agent string"

The string to use in the HTTP request with a name for the agent making the request. The default is "ServerTest 1.0".

This value often ends up in server logs. By using a unique value like the default, it should be easy to filter out requests made by this program from normal, human browser requests so as not to mess up statistics.

--config_file=filename, -c filename

The file from which to read option data before processing any further command line options. The format of the file is defined below. Note that this command has both a short and long form.

--help, -h

Show help information listing the command options.

--interactive

Start prompting for option values from the terminal (STDIN). This allows you to enter values without needing to edit the command line or have a configuration file. If there are no options or arguments on the command line, then "--interactive" is assumed.

All values are prompted for, and then option processing on the command line continues. A configuration file specified interactively is read after all the prompting has finished. This option may appear more than once (for example, to specify a configuration file and then allow its values to be overridden).

--logfile=filename, -l filename

The name of the file in which to save optional log. This file will be created if it does not already exist. Each time the program starts, a heading line is added to the file. New log entries are appended to the end.

If there is not an option with "restart=no", then the logfile is read (if it exists) and the accumulated values for each URL being tested are read in to let the calculations restart where they left off. The sequence number of the last poll executed is determined by looking for the highest poll sequence number in the logfile.

If the filename is null (e.g., --logfile=, or -l ""), no logging will be done and the polling sequence counting will start from 1.

--maxpolls=n, -m maxpolls

The number of tests to be made for each URL. After all the requests are made for a sequence number equal to maxpolls, the program returns. The default is 1 (a single test). If you plan to run this program for an extended period of time, restarting after any system shutdowns, you may want to set this number very high.

The program can usually be stopped early with ^C.

--pause=yes/no

If "yes", the program will prompt for the user to press ENTER on the terminal (STDIN) before exiting. This is useful on systems, such as Windows, where the program window disappears after exit. The default is "no".

--pollfrequency=seconds, -p seconds

The time to wait between polls. After all of the URLs are tested in a single poll sequence, the program waits this number of seconds. The default is 3600 (poll once an hour).

If the value is less than 10 seconds (it may be as low as zero), then the program will still wait 10 seconds if the "maxpolls" is greater than 100. This is to prevent the inadvertent unfriendly behavior of massive requests to a server. In the event that the program is being used on your own server and you want that type of behavior, you can set the $pollfrequencymin or $pollfrequencypollscutoff values in the program to override this check.

--restart=yes/no

Set restart to "no" if you want the logfile to accumulate independent sequences of data. Leave it out, or set it to "yes" to initialize from the logfile before starting.

--test=URL

A URL to test, without the access method (e.g., test=www.domain.com, or test=www.domain.com/file.html). Note that multiple --test and --test_agent options are allowed.

In addition, any argument to the program that does not start with "-" is assumed to be a URL to test.

--test_agent=URL "agent string"

A URL to test with agent string to be used for those requests only.

--timeout=seconds

The maximum time to tell the system to wait for each response before logging it as an unsuccessful, failed request. The default is 30 seconds.

URLn

A URL to test, without the access method (e.g., "www.domain.com"). The same as the "--test" option.

Configuration File Options

Option values may be read from a configuration file. The filename is specified with the "--config_file" or "-c" command line options. The general format of the configuration file is as follows:

   # comment
   name1=value1
   name2=value2 # optional comment

Blank lines are ignored. Most options in the configuration file override the command line options encountered before the file is read, or are overridden by command line options encountered after, except "test" which adds to the list of URLs to test.

The options that may be set are listed below. For a more detailed description of each option, see the Command Line Options descriptions above.

agent=agent text

The default value for Agent in request.

logfile=filename

If present, where to save a log.

maxpolls=n

Quit after this many total poll sequences.

pollfreqency=seconds

The amount of time to wait between each poll sequence.

restart=yes/no

Unless the option "restart=no" is present, parse logfile and start calculations from where we left off

test=URL

A URL to test with an HTTP GET request during each polling sequence, e.g., test=www.domain.com. Multiple test lines are allowed.

test=URL agent text

The same as the "test" option, with the addition of a specific agent text for this URL to be used instead of the default. For example:

     test=www.domain.com Test by me@mydomain.com

(The use of an email address lets the website owner find out who is doing this.)

timeout=seconds

The maximum time to wait for a response before considering it unsuccessful.

EXAMPLES

Here are three examples of invoking the program through the Perl system. It is assumed that the program is in the current directory and that the Perl system is in the search path. The first has all of the information on the command line and the second uses a configuration file. The third will result in prompts for the option values. Depending upon how the program is installed on your system, you may be able to execute it just by using "servertest" instead of "perl servertest.pl". In all cases, the options follow.

     perl servertest.pl -m 10 -p 5 "www.dom314.com"

     perl servertest.pl -c servertest.cfg -p 60

     perl servertest.pl

Here is an example of a configuration file:

     #
     # This is a sample configuration file
     #

     test=www.dom314.org
     test=www.dom314159.com

     logfile=servertest.log
     pollfrequency=900 # 15*60 = 15 minutes
     maxpolls=10000 # months...

     restart=yes

VERSION

This is servertest.pl v1.00. $Revision: 1.11 $

AUTHOR

Dan Bricklin, Software Garden, Inc.

COPYRIGHT

(c) Copyright 2004 Software Garden, Inc. All Rights Reserved.

See the Software License in the program file.