SGI Techpubs Library

Linux  »  Man Pages
find in page



NAME
       pmlogsummary - calculate averages of metrics stored in a PCP archive

SYNOPSIS
       pmlogsummary  [-abfFHiIlmMNsvxyz]  [-B  nbins] [-n pmnsfile] [-p preci-
       sion] [-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 met-
       ricname is a non-leaf  node  in  the  Performance  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 namespace 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 met-
              ric 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  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.

       -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 (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 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 aver-
              ages).

       -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 vari-
       able 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 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: stochas-
       tic 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-sepa-
       rated (unless the -f option is used).

       All  counter  metrics  which are measured in units of time will be con-
       verted to seconds before being rate converted and used in the pmlogsum-
       mary  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 differ-
       ent  timestamp formats, depending on the interval over which it is run.
       For an interval greater than 24 hours, the date is displayed  in  addi-
       tion  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 with-
       out 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 aver-
       age (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 met-
       ric 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(4).

SEE ALSO
       PCPIntro(1), pmchart(1), pmdumptext(1),  pmlogextract(1),  pmlogger(1),
       pmval(1), PMAPI(3), pmUnitsStr(3) and pmns(4).

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

Performance Co-Pilot                  SGI                      PMLOGSUMMARY(1)

Output converted with man2html


home/search | what's new | help