# pmdumptext

## NAME



           **pmdumptext** - dump performance metrics to an ASCII table
    


## SYNOPSIS



           **pmdumptext**[**-CFGHilmMNoruVXz?**]  [**-a** _archive_] [**-A** _align_] [**-c**
           _config_] [**-d** _delimiter_] [**-D** _debug_] [**-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 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, or an explict host: or
           archive/ prefix in the _metric_ (see below for more information),
           **pmdumptext** will contact the Performance Metrics Collector Daemon
           (PMCD) 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.
    
           By default **pmdumptext** will scale metric values to ``canonical''
           units of bytes, seconds and counts.  The one exception is with the
           **-r** option where the values are not scaled.  The **-u** option reports
           the units of each metric.
    
           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]
    
           When a _metric_ does not contain a host: or archive/ prefix, e.g.
           kernel.all.cpu.idle above, then the source of the metric is
           determined by the following rules:
           (a) PMCD on _host_ from the **-h** option if any, else
           (b) the _archive_ from the first **-a** option if any, else
           (c) the host from the first _metric_ prior to this one with a host:
               prefix if any, else
           (d) the archive from the first _metric_ prior to this one with an
               archive/ prefix if any, else
           (e) PMCD on the local host, which is equivalent to local::_metric_.
    
           The format of a _metric_ is further described in PCPIntro(1) in the
           PERFORMANCE METRIC SPECIFICATIONS section.  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.
    


## OPTIONS



           The command line options **-A**(or **--align**), **-O**(or **--origin**), **-S**(or
           **--start**) and **-T**(or **--finish**) 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** _archive_ , **--archive** =_archive_
                Specifies the historical _archive_ from which metrics can be
                obtained for a particular host.  _archive_ is the full path to
                an individual archive file, or the name of a directory con‐
                taining archives, or the basename of an archive - all previ‐
                ously created by pmlogger(1).  Multiple sets of archives
                (separated by commas or in different **-a** options) from differ‐
                ent 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** _config_ , **--config** =_config_
                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 nor‐
                malization value.  Empty lines and lines that begin with
                ``#'' are ignored.
    
           **-C** , **--check**
                Exit before dumping any values, but after parsing the met‐
                rics.  Metrics, instances, normals and units are listed if
                **-m** , **-l** , **-N** and/or **-u** are specified.
    
           **-d** _delimiter_ , **--delimiter** =_delimiter_
                Specify the _delimiter_ that separates each column of output.
                The _delimiter_ may only be a single character.
    
           **-f** _format_ , **--time-format** =_format_
                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 (e.g. '')
                will remove the timestamps from the output.
    
           **-F** , **--fixed**
                Output the values in a fixed width format of 6 characters.
                Positive numbers are represented as _dd_._dd_**u** and negative num‐
                bers as **[** -**]**_d_._dd_**u**.  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** , **--scientific**
                Output the values using the shortest of a scientific format
                or a decimal notation.
    
           **-h** _host_ , **--host** =_host_
                Fetch performance metrics from pmcd(1) on _host_ , rather than
                the default localhost.
    
           **-H** , **--headers**
                Show all headers before dumping any metric values.  This is
                equivalent to **-lmNu**.
    
           **-i** , **--interactive**
                Output the data in fixed width columns using fixed width val‐
                ues (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 trun‐
                cated.
    
           **-l** , **--source**
                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** , **--metrics**
                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 rele‐
                vant, 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** _pmnsfile_ , **--namespace** =_pmnsfile_
                Load an alternative local PMNS from the file _pmnsfile_.
    
           **-o** , **--offset**
                When a timestamp is being reported (i.e. unless an empty for‐
                mat 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** _precision_ , **--precision** =_precision_
                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** , **--raw**
                Output the raw metric values, do not convert counters to
                rates and do not scale values to ``canonical'' units.  This
                option also causes **pmdumptext** to ignore the normalization
                values for each metric.
    
           **-R** _lines_ , **--repeat** =_lines_
                Repeat the header every _lines_ of output.  This option is use‐
                ful 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** _samples_ , **--samples** =_samples_
                **pmdumptext** will terminate after this many samples.
    
           **-t** _interval_ , **--interval** =_interval_
                The _interval_ option follows the syntax described in
                PCPIntro(1), and in the simplest form may be an unsigned in‐
                teger (the implied units in this case are seconds).  The de‐
                fault interval is 1 second.
    
           **-u** , **--units**
                Output the units of the metrics before the first values, but
                after the metric names if **-m** is also specified.
    
           **-U** _string_ , **--unavailable** =_string_
                Change the output when values are unavailable to _string_.  The
                default string is ``?''.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-w** _width_ , **--widthfR=**_width_
                Set the column width of the output.  Strings will be truncat‐
                ed to this width, and maybe postfixed by ``...'' if the _width_
                is greater than 5.
    
           **-X** , **--extended**
                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** , **--hostzone**
                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** _timezone_ , **--timezone** =_timezone_
                Use _timezone_ for the date and time.  _Timezone_ is in the for‐
                mat of the environment variable **TZ** as described in
                environ(7).
    
           **-?** , **--help**
                Display usage message and exit.
    


## MULTIPLE SOURCES



           **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 previous‐
           ly 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 Uti‐
                  lization'' 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 in‐
           terval 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 parameter‐
           ize the file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values for these
           variables.  The **$PCP_CONF** variable may be used to specify an al‐
           ternative configuration file, as described in pcp.conf(5).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional diagnos‐
           tics on _stderr_ to help triage problems, although the information
           is sometimes cryptic and primarily intended to provide guidance
           for developers rather end-users.  _debug_ is a comma separated list
           of debugging options; use pmdbg(1) with the **-l** option to obtain a
           list of the available debugging options and their meaning.
    
           Debugging options specific to **pmdumptext** are as follows:
           ┌────────┬───────────────────────────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl0** │ detailed diagnostics for metrics, their source and    │
           │        │ timezone, metadata, units normalization, output for‐  │
           │        │ mat, etc.                                             │
           └────────┴───────────────────────────────────────────────────────┘
    


* * *