NAME

       pmdumptext - performance metrics dump to an ASCII table


SYNOPSIS

       pmdumptext     [-CFgHilmMNoruz]     [-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

       pmdumptext outputs the values of performance metrics  col­
       lected  live  or  from  a  Performance  Co-Pilot  (PCP(1))
       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 PCPIn­
       tro(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

       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 speci­
       fied 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 com­
              mas or in  different  -a  options)  from  different
              hosts  may  be given, but only one per host is per­
              mitted.  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 charac­
              ter.

       -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


       -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 post­
              fix  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 scien­
              tific 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 -E as fixed  point
              values  are not fixed width.  This option will also
              affect the output of -m and -u options as the  met­
              ric, 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 trun­
              cated,  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 pmns­
              file.

       -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  sec­
              onds from the start of the archive or the beginning
              of the execution of pmdumptext.

       -N     Output the normalization factors before the  metric
              values.

              not be used with -F as the precision  is  constant.
              The default precision is 3.

       -r     Output  the raw metric values, do not convert coun­
              ters 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.

       -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  vari­
              able 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  com­
       mand line or previously as the source of another metric.



UNIT CONVERSION

       All  metrics that have the semantics of counters are auto­
       matically converted to rates over the sample  time  inter­
       val.  In interactive mode, pmdumptext will also change the
       units of some metrics so that they are easier  to  compre­
       hend:

       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 (nanosec­
              onds 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, simultane­
       ously:

     $ 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
       bing with a simpler timestamp:

     $ pmdumptext -imu -h bing -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 sec­
       ond 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

       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

       pcp(1),  PCPIntro(1),  pmcd(1),  pmdumpmineset(1),  pmlog­
       ger(1), pmlogmerge(1), pmval(1), PMAPI(3), strftime(3) and
       environ(5).


Man(1) output converted with man2html