xenial (1) pmlogsummary.1.gz

Provided by: pcp_3.10.8build1_amd64 bug

NAME

       pmlogsummary - calculate averages of metrics stored in a PCP archive

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
       Performance  Co-Pilot  (PCP)  archive  log.  The default output prints time averages for both counter and
       non-counter metrics.  The archive log has the base name archive, 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 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(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 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 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), pmval(1),  PMAPI(3),  pmUnitsStr(3)
       and pmns(5).

DIAGNOSTICS

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