xenial (1) pmdumptext.1.gz

Provided by: pcp-gui_3.10.8build1_amd64 bug

NAME

       pmdumptext - dump performance metrics to an ASCII table

SYNOPSIS

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

DESCRIPTION

       pmdumptext  outputs the values of performance metrics collected live or from a Performance Co-Pilot (PCP)
       archive.  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 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

       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  an  archive  from  which  metrics  can be obtained for a particular host.  archive is the
              basename of an archive, previously created by pmlogger(1).  Multiple archives (separated by commas
              or in different -a options) from different hosts may be given, but only one 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.

       -g     Run in graphical user interface (GUI) mode, with pmtime being  used  for  VCR-alike  time  control
              functionality.

       -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 archive or the
              beginning of the execution of pmdumptext.

       -N     Output the normalization factors before the metric values.

       -p     Connect to pmtime(1) on the specified port.

       -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

       pmdumptext supports the dumping of metrics from multiple hosts or 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 archive for any one host.  Secondly, the hosts of any
       metrics  with  host  sources  must  correspond  to  the host of an archive, 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

       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

       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

       $PCP_VAR_DIR/pmns/*
                 default PMNS specification files

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

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