NAME | SYNOPSIS | DESCRIPTION | COMMAND LINE OPTIONS | MULTIPLE SOURCES | UNIT CONVERSION | EXAMPLES | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMDUMPTEXT(1)              General Commands Manual             PMDUMPTEXT(1)

NAME         top

       pmdumptext - dump performance metrics to an ASCII table

SYNOPSIS         top

       pmdumptext [-CFGHilmMNoruXz] [-A align] [-a archive[,archive,...]]
       [-c config] [-d delimiter] [-f format] [-h host] [-n pmnsfile] [-O
       offset] [-P precision] [-R lines] [-s sample] [-S starttime] [-t
       interval] [-T endtime] [-U string] [-w width] [-Z timezone] [metric
       ...]

DESCRIPTION         top

       pmdumptext outputs the values of performance metrics collected live
       or from a set of Performance Co-Pilot (PCP) archives.  By default,
       the metric values are displayed in tab separated columns, prefixed by
       a timestamp.

       Unless directed to another host by the -h option, or to one or more
       sets of archives by the -a option, pmdumptext will contact pmcd(1) on
       the local host to obtain the required information.

       pmdumptext may be run in interactive mode with the -i option which
       displays the values in equal width columns.  Without this option, no
       attempt is made to line up any values allowing the output to be
       easily parsed by other applications.

       The format of the output can be further controlled by changing the
       precision of the values with -P, the width of the columns with -w,
       and the format of the values with the -G and -F options for the
       shortest of scientific or fixed digits, and a fixed width format,
       respectively.

       The metrics to be dumped can be listed on the command line, in a
       config file, or piped to pmdumptext on stdin.  A metric consists of
       an optional source (host or archive), the metric name, and an
       optional instance list immediately after the name.  A colon is used
       to separate a host name from the metric, and a forward slash (``/'')
       to separate an archive name from the metric.  Instances are enclosed
       in square brackets and a comma is used between each instance if more
       than one is stated.  For example, some legal metrics are:

               kernel.all.cpu.idle
               myhost:kernel.all.cpu.idle[cpu0,cpu3]
               /path/to/myarchive/kernel.all.cpu.idle[cpu1]

       The format of a metric is further described in PCPIntro(1).  A
       normalization value may optionally follow a metric name in a config
       file or on stdin.  The metric value will be scaled by this value.
       For example, if the file system ``/dev/root'' has a capacity of
       1965437 bytes, then the percentage of the file system that is used
       could be dumped with this config:

               filesys.used[/dev/root] 19654.37

       A normalization value may not be used with metrics specified as
       command line arguments.

       A metric name is not required to be a leaf node in the Performance
       Metrics Name Space (PMNS), except when one or more instances are
       specified.  For example, to dump all file system metrics, only
       filesys is required to dump filesys.capacity, filesys.used,
       filesys.free etc.

COMMAND LINE OPTIONS         top

       The command line options -A, -O, -S and -T control the alignment,
       offset, start and end time when visualizing metrics from archives.
       These options are common to most Performance Co-Pilot tools and are
       fully described in PCPIntro(1).

       The other available options are:

       -a     Specify a set of archive from which metrics can be obtained
              for a particular host.  archive is the name of a directory
              containing archives, or the basename of an archive, previously
              created by pmlogger(1).  Multiple sets of archives (separated
              by commas or in different -a options) from different hosts may
              be given, but only one set of archives per host is permitted.
              Any metrics that are not associated with a specific host or
              archive will use the first archive as their source.

       -C     Exit before dumping any values, but after parsing the metrics.
              Metrics, instances, normals and units are listed if -m, -l, -N
              and/or -u are specified.

       -c     If no metrics are listed on the command line, a config file
              can be used to specify the metrics to be dumped.  Unlike the
              command line metrics, each metric may be followed by a
              normalization value.  Empty lines and lines that begin with
              ``#'' are ignored.

       -d     Specify the delimiter that separates each column of output.
              The delimiter may only be a single character.

       -f     Use the format string for formatting the timestamp with each
              set of values.  The syntax of this string is the same as that
              described in strftime(3).  An empty format string (eg. '')
              will remove the timestamps from the output.

       -F     Output the values in a fixed width format of 6 characters.
              Positive numbers are represented as dd.ddu and negative
              numbers as [-]d.ddu.  The postfix multiplier may have the
              values K(10^3), M(10^6), G(10^9) and T(10^12).  For example,
              4567 would be displayed as 4.57K, even if the units of the
              metric are bytes.

       -G     Output the values using the shortest of a scientific format or
              a decimal notation.

       -h     Fetch performance metrics from pmcd(1) on host, rather than
              the default localhost.

       -H     Show all headers before dumping any metric values.  This is
              equivalent to -lmNu.

       -i     Output the data in fixed width columns using fixed width
              values (see -F) so that it is human-readable.  This option may
              not be used with -P as fixed point values are not fixed width.
              This option will also affect the output of -m and -u options
              as the metric, instance and unit names will be truncated.

       -l     Show the source of the metrics.  In interactive mode, the host
              of the metrics is shown.  In non-interactive mode, this option
              shows the source of the metrics with the metric name even if
              -m is not specified.

       -m     Output the metric names before the metric values.  The source
              and units of the metrics may also be dumped with the -l and -u
              options respectively.  If in interactive mode, the metrics
              names may be truncated, and the instance names, where
              relevant, are also truncated on the follow line.

       -M     Output the column number and complete metric names before
              dumping any values.  If the -l flag is also specified, the
              source of the metrics is also shown.

       -n     Load an alternative local PMNS from the file pmnsfile.

       -o     When a timestamp is being reported (ie. unless an empty format
              string is given with the -f option), the timestamp is prefixed
              with the offset in seconds from the start of the set of
              archives or the beginning of the execution of pmdumptext.

       -N     Output the normalization factors before the metric values.

       -P     Set the precision of the values.  This option may not be used
              with -F as the precision is constant.  The default precision
              is 3.

       -r     Output the raw metric values, do not convert counters to
              rates.  This option also causes pmdumptext to ignore the
              normalization values for each metric.

       -R     Repeat the header every lines of output.  This option is
              useful in interactive mode when using a graphical window to
              avoid the header scrolling beyond the window's buffer, and to
              realign the header if the window is resized.

       -s     pmdumptext will terminate after this many samples.

       -t     The interval argument follows the syntax described in
              PCPIntro(1), and in the simplest form may be an unsigned
              integer (the implied units in this case are seconds).  The
              default interval is 1.0 seconds.

       -u     Output the units of the metrics before the first values, but
              after the metric names if -m is also specified.

       -U     Change the output when values are unavailable to string.  The
              default string is ``?''.

       -w     Set the column width of the output.  Strings will be truncated
              to this width, and maybe postfixed by ``...'' if the width is
              greater than 5.

       -X     Output the column number and complete metric names, one-per-
              line, both before dumping the first set of values and again
              each time the header is repeated.

       -z     Use the local timezone of the host that is the source of the
              performance metrics, as identified by either the -h or the
              first -a options.  The default is to use the timezone of the
              local host.

       -Z     Use timezone when displaying the date and time.  Timezone is
              in the format of the environment variable TZ as described in
              environ(7).

MULTIPLE SOURCES         top

       pmdumptext supports the dumping of metrics from multiple hosts or set
       of archives.  The metrics listed on the command line or in the config
       file may have no specific source or come from different sources.

       However, restrictions apply when archives are specified on the
       command line (-a) and/or in the configuration file.  Firstly, there
       may be only one set of archives for any one host.  Secondly, the
       hosts of any metrics with host sources must correspond to the host of
       a set of archives, either on the command line or previously as the
       source of another metric.

       The options -a and -h may not be used together.

UNIT CONVERSION         top

       All metrics that have the semantics of counters are automatically
       converted to rates over the sample time interval.  In interactive
       mode, pmdumptext will also change the units of some metrics so that
       they are easier to comprehend:

       o      All metrics with space units (bytes to terabytes) are scaled
              to bytes.  Note that 1024 bytes with be represented as 1.02K,
              not 1.00K.

       o      Metrics that are counters with time units (nanoseconds to
              hours) represent time utilization over the sample interval.
              The unit strings of such metrics is changed to ``Time
              Utilization'' or abbreviated to ``util'' and the values are
              normalized to the range zero to one.

EXAMPLES         top

       o To examine the load on two hosts foo and bar, simultaneously:

     $ pmdumptext -il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]'
                  Source        foo     bar
     Wed Jul 30 11:37:53      0.309   0.409
     Wed Jul 30 11:37:54      0.309   0.409
     Wed Jul 30 11:37:55      0.309   0.409

       o To output the memory utilization on a remote host called bong with
       a simpler timestamp:

     $ pmdumptext -imu -h bong -f '%H:%M:%S' mem.util
       Metric        kernel  fs_ctl  _dirty  _clean    free    user
        Units             b       b       b       b       b       b
     09:32:28         8.98M   0.97M   0.00    3.90M   7.13M  46.13M
     09:32:29         8.99M   0.98M   0.00    5.71M   5.39M  46.03M
     09:32:30         8.99M   1.07M   0.00    5.81M   4.55M  46.69M
     09:32:31         9.03M   1.16M   0.00    6.45M   3.48M  47.00M
     09:32:32         9.09M   1.18M  20.48K   6.23M   3.29M  47.30M

       o To dump all metrics collected in an archive at a 30 second interval
       to a file for processing by another tool:

     $ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile

FILES         top

       $PCP_VAR_DIR/pmns/*
                 default PMNS specification files

PCP ENVIRONMENT         top

       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

       pmchart(1), pmtime(1), PCPIntro(1), pmcd(1), pmlogger(1),
       pmlogextract(1), pmrep(1), pmval(1), PMAPI(3), strftime(3) and
       environ(7).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-05-03.  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 man-pages@man7.org

Performance Co-Pilot                 SGI                       PMDUMPTEXT(1)

Pages that refer to this page: pcpintro(1)pmchart(1)pmclient(1)pminfo(1)pmlogsummary(1)pmrep(1)pmval(1)pmview(1)