NAME

       qslog - collects request statistics from access log data.

SYNOPSIS

       qslog -f <format_string> -o <out_file> [-p[c|u[c]] [-v]] [-x [<num>]] [-u <name>] [-m] [-c <path>]

DESCRIPTION

       qslog  is  a real time access log analyzer. It collects the data from stdin. The output is written to the
       specified file every minute and includes the following entries:
         - requests per second (r/s)
         - number of requests within measured time (req)
         - bytes sent to the client per second (b/s)
         - bytes received from the client per second (ib/s)
         - response status codes within the last minute (1xx,2xx,3xx,4xx,5xx)
         - average response duration (av)
         - average response duration in milliseconds (avms)
         - distribution of response durations in seconds within the last minute (<1s,1s,2s,3s,4s,5s,>5s)
         -  distribution   of   response   durations   faster   than   a   second   within   the   last   minute
       (0-49ms,50-99ms,100-499ms,500-999ms)
         - number of established (new) connections within the measured time (esco)
         - average system load (sl)
         - free memory (m) (not available for all platforms)
         - number of client ip addresses seen withn the last 600 seconds (ip)
         - number of different users seen withn the last 600 seconds (usr)
         - number of events identified by the 'E' format character
         -  number  of  mod_qos  events  within  the  last minute (qV=create session, qv=VIP IP,qS=session pass,
       qD=access  denied,  qK=connection  closed,  qT=dynamic   keep-alive,   qL=request/response   slow   down,
       qs=serialized request,  qA=connection abort, qU=new user tracking cookie)

OPTIONS

       -f <format_string>
              Defines  the  log data format and the positions of data elements processed by this utility. See to
              the 'LogFormat' directive of the httpd.conf file to see the  format  definitions  of  the  servers
              access log data.
                   qslog knows the following elements:
                   I defines the client ip address (%h)
                   R defines the request line (%r)
                   S defines HTTP response status code (%s)
                   B defines the transferred bytes (%b or %O)
                   i defines the received bytes (%I)
                   D defines the request duration in microseconds (%D)
                   t defines the request duration in milliseconds (may be used instead of D)
                   T defines the request duration in seconds (may be used instead of D or t) (%T)
                   k defines the number of keepalive requests on the connection (%k)
                   U defines the user tracking id (%{mod_qos_user_id}e)
                   Q defines the mod_qos_ev event message (%{mod_qos_ev}e)
                   C defines the element for the detailed log (-c option), e.g. "%U"
                   s arbitrary counter to add up (sum within a minute)
                   a arbitrary counter to build an average from (average per request)
                   A arbitrary counter to build an average from (average per request)
                   M arbitrary counter to measure the maximum value reached (peak)
                   E comma separated list of event strings
                   c content type (%{content-type}o), available in -pc mode only
                   m request method (GET/POST) (%m), available in -pc mode only
                   . defines an element to ignore (unknown string)

       -o <out_file>
              Specifies the file to store the output to. stdout is used if this option is not defined.

       -p     Used  for post processing when reading the log data from a file (cat/pipe). qslog is started using
              it's offline mode (extracting the time stamps from the log lines) in order to process existing log
              files.  The  option  "-pc" may be used alternatively if you want to gather request information per
              client (identified by IP address (I) or user tracking id (U) showing how many request each  client
              has  performed  within  the  captured  period  of  time).  "-pc"  supports  the  format characters
              IURSBTtDkMEcm. The option "-pu" collects statistics on a per URL level (supports format characters
              RSTtD). "-puc" is very similar to "-pu" but cuts the end (handler) of each URL.

       -v     Verbose mode.

       -x [<num>]
              Rotates  the  output  file once a day (move). You may specify the number of rotated files to keep.
              Default are 14.

       -u <name>
              Becomes another user, e.g. www-data.

       -m     Calculates free system memory every minute.

       -c <path>
              Enables the collection of  log  statitics  for  different  request  types.  'path'  specifies  the
              necessary  rule file. Each rule consists of a rule identifier and a regular expression to identify
              a request seprarated by a colon, e.g., 01:^(/a)|(/c). The regular expressions are matched  against
              the log data element which has been identified by the 'C' format character.

VARIABLES

       The following environment variables are known to qslog:

       QSEVENTPATH=<path>
              Defines  a  file  containing  a  comma  or new line separated list of known event strings expected
              within the log filed identified by the 'E' format character.

       QSCOUNTERPATH=<path>
              Defines a file  containing  a  by  new  line  separated  list  of  rules  which  reflect  possible
              QS_ClientEventLimitCount  directive settings (for simulation purpose / -pc option). The 'E' format
              character defines the event string in the log to match (literal string) the 'event1' and  'event2'
              event names against.

              Rule syntax: <name>:<event1>-<n>*<event2>/<duration>=<limit>
                   'name'  defines  the  name you have given to the rule entry and is logged along with with the
              number of times the 'limit' has been reached within the 'duration'.
                   'event1' defines the variable name (if found in 'E') to increment the counter.
                   'event2' defines the variable name (if found in  'E')  to  decrement  the  counter  (and  the
              parameter 'n' defines by how much).
                   'duration'  defines  the  measure interval (in seconds) used for the QS_ClientEventLimitCount
              directive.
                   'limit' defines the threshold (number) defined for the QS_ClientEventLimitCount directive.

              Note: If the 'name' parameter is prefixed by 'STATUS', the rule is applied against the HTTP status
              code  'S'  and  the  'event1' string shall contain a list of relevant status codes separated by an
              underscore (while 'event2' is ignored).

EXAMPLE

       Configuration using pipped logging:

         CustomLog "|/usr/bin/qslog -f ISBDQ -x -o /var/log/apache/stat.csv" "%h %>s %b %D %{mod_qos_ev}e"

       Post processing:

         LogFormat "%t %h \"%r\" %>s %b \"%{User-Agent}i\" %T"
         cat access.log | qslog -f ..IRSB.T -o stat.csv -p

SEE ALSO

       qsdt(1),  qsexec(1),  qsfilter2(1),  qsgeo(1),  qsgrep(1),  qshead(1),  qslogger(1),  qspng(1),  qsre(1),
       qsrespeed(1), qsrotate(1), qssign(1), qstail(1)

AUTHOR

       Pascal Buchbinder, http://mod-qos.sourceforge.net/