pmlogsummary(1) — Linux manual page


PMLOGSUMMARY(1)          General Commands Manual         PMLOGSUMMARY(1)

NAME         top

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

SYNOPSIS         top

       pmlogsummary [-abfFHiIlmMNsvVxyz?]  [-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) archives.  The default output prints time averages
       for both counter and non-counter metrics.  The set of archives 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 archives 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.

       Metrics with counter semantics are converted to rates before
       being evaluated.

OPTIONS         top

       The available command line options are:

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

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

       -B nbins, --bins=nbins
            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 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, --header
            Print a one-line header at the start showing what each field

       -i, --mintime
            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, --maxtime
            Also print the time at which the maximum value was logged.
            The format of this timestamp is described in the ``OUTPUT
            FORMAT'' section below.

       -l, --label
            Also print the archive label, showing the archive 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.

       -m, --minimum
            Also print the minimum logged value for each metric.

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

       -n pmnsfile, --namespace=pmnsfile
            Load an alternative Performance Metrics Name Space (PMNS(5))
            from the file pmnsfile.

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

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

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

       -S starttime, --start=starttime
            Set the starttime of the time window.  Refer to PCPIntro(1)
            for a complete description of the syntax for starttime.

       -T endtime, --finish=endtime
            Set the endtime of the time window.  Refer to PCPIntro(1)
            for a complete description of the syntax for endtime.

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

       -V, --version
            Display version number and exit.

       -x   Print stochastic averages instead of the default (time

       -y, --samples
            Also print the number of samples encountered in the set of
            archives for each metric.

       -z, --hostzone
            Change 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.

       -Z timezone, --timezone=timezone
            By default, pmlogsummary reports the time of day according
            to the local timezone on the system where pmlogsummary is
            run.  Change the timezone to timezone in the format of the
            environment variable TZ as described in environ(7).

       -?, --help
            Display usage message and exit.

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

       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

       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 (*).

EXAMPLES         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

SEE ALSO         top

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

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 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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)