Provided by: pcp_4.3.1-1_amd64 bug

NAME

       pmlogsummary - calculate averages of metrics stored in a set of PCP archives

SYNOPSIS

       pmlogsummary  [-abfFHiIlmMNsvxyz]  [-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 set of Performance Co-Pilot (PCP) archive logs.  The default output prints
       time averages for both counter and non-counter  metrics.   The  set  of  archive  logs  is
       identified  by archive, which is a comma-separated list of names, each of which may be the
       base name of an archive or the name of a directory containing one or more  archives.   The
       archive logs are typically created using pmlogger(1).

       The  metrics  of  interest are named in the metricname arguments.  If metricname is a non-
       leaf node in  the  Performance  Metrics  Name  Space  (pmns(5)),  then  pmlogsummary  will
       recursively  descend  the PMNS and report on all leaf nodes.  If no metricname argument is
       given, the root of the namespace is used.

       Normally pmlogsummary operates on the  default  pmns(5),  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).

       -f     Spreadsheet format - the tab character is used to delimit each field printed.  This
              option is intended to allow pmlogsummary output to be imported directly into common
              spreadsheet applications.

       -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 applications which support  the  Comma  Separated  Value  (.csv)
              format.

       -H     Print a one-line header at the start showing what each field represents.

       -l     Also print the archive label, showing the log format version, the time and date for
              the start and 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 metric.

       -M     Also print the maximum logged value for each metric.

       -s     Print (only) the sum of all logged values for each metric.

       -N     Suppress any warnings resulting from individual archive fetches (default).

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

       -v     Report (verbosely) on warnings resulting from individual archive fetches.

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

       -y     Also  print  the  number  of  samples  encountered  in the set of archives 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(7).  The -z  option  changes
       the  timezone  to  the  local  timezone  at the host that is the source of the performance
       metrics, as specified in the label record of the archive log.

OUTPUT FORMAT

       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 pmUnitsStr(3).

       Given either of the -i or  -I  options,  pmlogsummary  produces  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 millisecond precision, but without the date).

NOTES

       The average for an individual metric is calculated as follows:

       Non-counter metrics are averaged using stochastic averaging  -  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).

       Counter metrics are averaged using time averaging (by 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 set of archives 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 statistical output, which describes one
       instance of the network.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/pmlogger/hostname
                 Default  directory  for  PCP  archives  containing  performance  metric   values
                 collected from the 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(5).

SEE ALSO

       PCPIntro(1), pmchart(1), pmdumptext(1), pmlogextract(1), pmlogger(1), pmrep(1),  pmval(1),
       PMAPI(3), pmUnitsStr(3) and pmns(5).

DIAGNOSTICS

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