Provided by: pcp-gui_1.5.11_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(5).

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

SEE ALSO

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