NAME

       pmlogsummary  -  calculate averages of metrics stored in a
       PCP archive


SYNOPSIS

       pmlogsummary [-abfFiIlmMNxyz] [-B nbins] [-n pmnsfile] [-p
       precision]  [-S  starttime]  [-T  endtime]  [-Z  timezone]
       archive [metricname ...]


DESCRIPTION

       pmlogsummary prints statistical information about  metrics
       of  numeric  type  contained within the files of a Perfor­
       mance Co-Pilot (PCP)  archive  log.   The  default  output
       prints time averages for both counter and non-counter met­
       rics.  The archive log has the base  name  archive,  typi­
       cally created using pmlogger(1).

       The  metrics of interest are named in the metricname argu­
       ments.  If metricname is a non-leaf node  in  the  Perfor­
       mance Metrics Name Space (pmns(4)), then pmlogsummary will
       recursively descend the PMNS and report on all leaf nodes.
       If no metricname argument is given, the root of the names­
       pace is used.

       Normally pmlogsummary operates  on  the  default  pmns(4),
       however  if  the  -n  option  is  specified an alternative
       namespace is loaded from the file pmnsfile.

       The command line options -S and -T can be used to  specify
       a  time  window  over  which metrics should be summarized.
       These options are  common  to  most  Performance  Co-Pilot
       tools and are fully described in PCPIntro(1).

       The  remaining options control the specific information to
       be reported.  Metrics with counter semantics are converted
       to rates before being evaluated.

       -a     Print  all  information.   This  is  equivalent  to
              -blmMy.

       -b     Print  both  forms  of  averaging,  that  is   both
              stochastic and time averaging.

       -B     Print the approximate distribution of values, using
              histogram bins such that the value range (minimum -
              maximum)  for  each  metric is divided equally into
              nbins bins, and each bin accumulates the  frequency
              of  observed  values  in  the  corresponding range.
              Refer to the ``OUTPUT FORMAT'' section below for  a
              description  of  how  the distribution of values is
              reported).

              delimit   each   field  printed.   This  option  is
              intended  to  allow  pmlogsummary  output   to   be
              imported  directly into common spreadsheet applica­
              tions.

       -F     Spreadsheet format - the comma character is used to
              delimit   each   field  printed.   This  option  is
              intended  to  allow  pmlogsummary  output   to   be
              imported  directly into common spreadsheet applica­
              tions  which  support  the  Comma  Separated  Value
              (.csv) format.

       -l     Also  print the archive label, showing the log for­
              mat version, the time and date for  the  start  and
              (current)  end  of the archive time window, and the
              host from which the performance metrics values were
              collected.

       -i     Also  print the time at which the minimum value was
              logged.  The format of this timestamp is  described
              in the ``OUTPUT FORMAT'' section below.

       -I     Also  print the time at which the maximum value was
              logged.  The format of this timestamp is  described
              in the ``OUTPUT FORMAT'' section below.

       -m     Also  print  the minimum logged value for each met­
              ric.

       -M     Also print the maximum logged value for  each  met­
              ric.

       -N     Suppress  any  warnings  resulting  from individual
              archive fetches.

       -p     Print all floating  point  numbers  with  precision
              digits after the decimal place.

       -x     Print  stochastic  averages  instead of the default
              (time averages).

       -y     Also print the number of samples encountered in the
              archive for each metric.

       By default, pmlogsummary reports the time of day according
       to the local timezone on the system where pmlogsummary  is
       run.   The  -Z  option changes the timezone to timezone in
       the format of the environment variable TZ as described  in
       environ(5).   The  -z  option  changes the timezone to the
       local timezone at the host that is the source of the  per­
       formance  metrics, as specified in the label record of the
       archive log.

       The  pmlogsummary  output  format  is  spartan  as  it  is
       intended  to  be post-processed with standard tools.  This
       means that there is no  annotation  associated  with  each
       output  field  which  would  make  processing harder.  The
       intention is that pmlogsummary output be massaged  into  a
       format  which  can  be  used  by a spreadsheet program, is
       suitable for inclusion in a web page, or whatever.

       For each metric, pmlogsummary  produces  a  single  output
       line as follows:

          metricname  value(s) units

       For metrics with multiple instances, pmlogsummary produces
       multiple lines of output as follows:

          metricname ["instance 1"] value(s) units
          metricname ["instance 2"] value(s) units
          metricname ["instance N"] value(s) units

       The printed value(s) for each metric  always  follow  this
       order:  stochastic average, time average, minimum, minimum
       timestamp,  maximum,  maximum  timestamp,  count,  [bin  1
       range],  bin  1  count,  ...  [bin nbins range], bin nbins
       count.  The individual values for each metric  are  space-
       separated (unless the -f option is used).

       All  counter  metrics  which are measured in units of time
       will be converted to seconds before being  rate  converted
       and  used  in  the  pmlogsummary calculations.  The values
       calculated for these metrics are also printed in  seconds.

       The  units  will  be  displayed in the format described by
       pmUnitStr(3).

       Given either of the -i or -I  options,  pmlogsummary  pro­
       duces  two  different  timestamp formats, depending on the
       interval over which it is run.  For  an  interval  greater
       than  24  hours,  the date is displayed in addition to the
       time at which the maxima and/or minima occurred.   If  the
       extent  of the data being checked is less than 24 hours, a
       more precise format is used (time is displayed  with  mil­
       lisecond precision, but without the date).


NOTES

       The average for an individual metric is calculated as fol­
       lows:

       Non-counter metrics are averaged using stochastic  averag­
       ing  - each observation has an equal weighting towards the
       calculation of the average (the sum of all values  divided
       by the total number of values, for each metric).

       default), but the -x option can be used  to  specify  that
       counters  be averaged using the stochastic method instead.
       When calculating a time average, the sum of the product of
       each  sample  value  multiplied  by  the  time  difference
       between each sample, is divided by  the  total  time  over
       which that metric was logged.

       Counter  metrics whose measurements do not span 90% of the
       archive will be printed with the metric name  prefixed  by
       an asterisk (*).


EXAMPLE

       $ pmlogsummary -aN -p 1 -B 3 surf network.interface.out.bytes
       Log Label (Log Format Version 1)
       Performance metrics from host www.sgi.com
         commencing Tue Jan 14 20:50:50.317 1997
         ending     Wed Jan 29 10:13:07.387 1997
       network.interface.out.bytes ["xpi0"] 202831.3 202062.5 20618.7 \
            1235067.7 971 [<=425435.0] 912 [<=830251.4] 42 [<=1235067.7] \
            17 byte / sec
       network.interface.out.bytes ["xpi1"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \
            1033 [] 0 [] 0 byte / sec
       network.interface.out.bytes ["et0"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \
            1033 [] 0 [] 0 byte / sec
       network.interface.out.bytes ["lo0"] 899.0 895.2 142.6 9583.1 1031 \
            [<=3289.4] 1027 [<=6436.2] 3 [<=9583.1] 1 byte / sec

       A description of each field in the first line of statisti­
       cal output, which  describes  one  instance  of  the  net­
       work.interface.out.bytes metric, follows:
       +--------------+-------------------------------------------+
       |    Field     |                  Meaning                  |
       +--------------+-------------------------------------------+
       |["xpi0"]      | instance name                             |
       |202831.3      | stochastic average                        |
       |202062.5      | time average                              |
       |20618.7       | minimum value                             |
       |1235067.7     | maximum value                             |
       |971           | total number of values for this instance  |
       |[<=425435.0]  | range for first bin  (20618.7-425435.0)   |
       |912           | number of values in first bin             |
       |[<=830251.4]  | range for second bin  (425435.0-830251.4) |
       |42            | number of values in second bin            |
       |[<=1235067.7] | range for third bin  (830251.4-1235067.7) |
       |17            | number of values in third bin             |
       |byte / sec    | base units for this metric                |
       +--------------+-------------------------------------------+

FILES

       $PCP_VAR_DIR/pmns/*
                 default PMNS specification files
       $PCP_LOG_DIR/pmloggerhostname
                 Default  directory  for  PCP archives containing

                 host hostname.


PCP ENVIRONMENT

       Environment  variables  with  the  prefix PCP_ are used to
       parameterize the file and directory names used by PCP.  On
       each  installation,  the  file  /etc/pcp.conf contains the
       local values for these variables.  The $PCP_CONF  variable
       may  be used to specify an alternative configuration file,
       as described in pcp.conf(4).


SEE ALSO

       PCPIntro(1), pmdumptext(1), pmlogextract(1),  pmlogger(1),
       pmval(1), PMAPI(3), pmUnitStr(3) and pmns(4).


DIAGNOSTICS

       All are generated on standard error and are intended to be
       self- explanatory.


Man(1) output converted with man2html