PMLOGSUMMARY(1)            General Commands Manual           PMLOGSUMMARY(1)

NAME         top

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

SYNOPSIS         top

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

DESCRIPTION         top

       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

       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

       -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

       -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

       -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

       -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         top

       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

          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         top

       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         top

       $ pmlogsummary -aN -p 1 -B 3 surf network.interface.out.bytes
       Log Label (Log Format Version 1)
       Performance metrics from host
         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         top

                 default PMNS specification files
                 Default directory for PCP archives containing performance
                 metric values collected from the host hostname.


       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         top

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

DIAGNOSTICS         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2019-07-28.  (At that time, the date of the most recent commit that
       was found in the repository was 2019-07-26.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                     PMLOGSUMMARY(1)

Pages that refer to this page: ganglia2pcp(1)pmdiff(1)pmlogcheck(1)pmrep(1)sar2pcp(1)LOGARCHIVE(5)