pmdumptext(1)
NAME
pmdumptext - dump performance metrics to an ASCII table
SYNOPSIS
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
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
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
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
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), pmrep(1), pmval(1), PMAPI(3), strftime(3) and environ(7).
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
