PMDUMPTEXT(1)

📦
version 7.2.2 · 5 versions
, in arch rolling, fedora 43, fedora 44, ubuntu stonking

🌸 pmdumptext — the Gen Z field guide 💅

okay bestie, listen up: this is pmdumptext from the General Commands Manual, section 1. it dumps performance metrics into an ASCII table and honestly? it's giving spreadsheet but make it ✨observability✨. let's go 🦋

✨ 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 ✨

so pmdumptext outputs the values of performance metrics — either collected live, or pulled out of a set of Performance Co-Pilot (PCP) archives. by default, the metric values show up in tab separated columns, with a timestamp sitting in front of them like a little name tag 🫶

unless you point it somewhere else with the -h option, or at one or more sets of archives with the -a option, or you slap an explicit host: or archive/ prefix on the metric itself (more on that below, iykyk), pmdumptext will go talk to the Performance Metrics Collector Daemon (PMCD) on the local host to get everything it needs. no cap 💖

pmdumptext can also run in interactive mode with the -i option, which displays the values in equal width columns (so pretty, so aligned 🌈). without that option, it makes zero attempt to line anything up — which is lowkey the whole point, because it means other applications can parse the output easily. iconic behaviour honestly.

you can control the output format even more: change the precision of the values with -P, change the width of the columns with -w, and change the format of the values with the -G and -F options — those give you the shortest of scientific-or-fixed digits, and a fixed width format, respectively. chef's kiss 💅

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. and the -u option reports the units of each metric, which is so helpful of it ⭐

the metrics to be dumped can be:

  • listed on the command line,
  • put 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 separates a host name from the metric, and a forward slash (/) separates an archive name from the metric. instances go inside square brackets, and a comma goes between each instance if you're listing more than one. 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 doesn't have a host: or archive/ prefix — like kernel.all.cpu.idle up there 👆 — then the source of the metric gets decided by these rules, in order:

(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 described even further in PCPIntro(1), in the PERFORMANCE METRIC SPECIFICATIONS section. go read it, bestie, it's a whole vibe 📖

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
⚠️ heads up: a normalization value may not be used with metrics specified as command line arguments. periodt.

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. she's efficient like that 💜

✨ 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 containing archives, or the basename of an archive — all 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 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 normalization value. empty lines and lines that begin with # are ignored. ✨
  • -C, --check — 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. a little sneak preview, no data spilled 🍓
  • -d delimiter, --delimiter=delimiter — specify the delimiter that separates each column of output. the delimiter may only be a single character. one. character. that's the rule 💅
  • -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. bye bye timestamps 👋
  • -F, --fixed — 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. math girlie behaviour 🧮
  • -G, --scientific — output the values using the shortest of a scientific format or a decimal notation. glow up 🔥
  • -h host, --host=host — fetch performance metrics from pmcd(1) on host, rather than the default localhost. go visit, bestie 🌍
  • -H, --headers — show all headers before dumping any metric values. this is equivalent to -lmNu. the full fit-check before the show 🌸
  • -i, --interactive — 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, --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 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. numbered like a ranked list, iconic 📋
  • -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 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 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. raw and unfiltered, we love that 💀
  • -R lines, --repeat=lines — 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. very considerate of her 🪟
  • -s samples, --samples=samples — pmdumptext will terminate after this many samples. that's a wrap ✨
  • -t interval, --interval=interval — the interval option 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 second. tick tock 🕰️
  • -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 ?. so when the data ghosts you, you get to choose the excuse 🙈
  • -V, --version — display version number and exit. 👑
  • -w width, --widthfR=width — 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, --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. she's thorough 💅
  • -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 format of the environment variable TZ as described in environ(7). 🕐
  • -?, --help — display usage message and exit. help a girl out 🫶

✨ MULTIPLE SOURCES ✨

pmdumptext supports the dumping of metrics from multiple hosts or sets of archives. the metrics listed on the command line or in the config file may have no specific source, or come from different sources. mixing and matching, we love to see it 🌈

however, restrictions apply when archives are specified on the command line (-a) and/or in the configuration file:

  1. there may be only one set of archives for any one host.
  2. 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. pick a lane, bestie 😭

🔄 UNIT CONVERSION 🔄

Okay bestie, this part is kinda the glow-up phase. Every metric that has the semantics of a counter gets automatically converted to rates over the sample time interval. That's just how it works, no asking, it's automatic. 💅

And in interactive mode, pmdumptext is even extra and changes the units on some metrics so your human brain can actually process them:

  • All metrics with space units (bytes all the way up to terabytes) get scaled to bytes. And heads up — this is the iconic detail — 1024 bytes is represented as 1.02K, NOT 1.00K. Yes, really. That's not a typo, that's just the vibe. 🫶
  • Metrics that are counters with time units (nanoseconds through hours) represent time utilization over the sample interval. The unit strings of those metrics get changed to Time Utilization, or abbreviated to util if you're being casual, and the values are normalized to the range zero to one. Clean. Tidy. Slay. ✨

🌸 EXAMPLES 🌸

Not me giving you actual receipts of this tool in the wild. Study them, they're giving main character energy. 👑

1. Say you wanna examine the load on two hosts, foo and bar, at the same time:

$ 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

2. Wanna output the memory utilization on a remote host called bong, but with a simpler timestamp? Say less:

$ 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

3. And if you want to dump all metrics collected in an archive, at a 30 second interval, into a file so another tool can chew on it:

$ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile

It's giving pipeline. It's giving delegation. We love a tool that plays well with others. 🦋

🎀 FILES 🎀

  • $PCP_VAR_DIR/pmns/* — the default PMNS specification files. The originals. The blueprint files. 🗂️

🌈 PCP ENVIRONMENT 🌈

So here's the tea on config, bestie. Environment variables with the prefix PCP_ are used to parameterize the file and directory names that PCP uses. Every single installation has a file at /etc/pcp.conf that holds the local values for all these variables. 💖

And if you want to be different (respect), the $PCP_CONF variable can be used to specify an alternative configuration file, exactly as described in pcp.conf(5).

Also, for environment variables that affect PCP tools generally (not just this one), go look at pmGetOptions(3). iykyk. 🧚

💀 DEBUGGING OPTIONS 💀

The -D or --debug option turns on additional diagnostics on stderr to help triage problems. Lowkey though? That info is sometimes cryptic, and it's primarily intended to give guidance for developers rather than for end-users. So if you're just vibing as a normal user, you might be reading straight-up riddles. 😭

debug is a comma separated list of debugging options. And listen — to get the list of available debugging options and what they mean, use pmdbg(1) with the -l option. That's your cheat sheet. 📝

The debugging options specific to pmdumptext are as follows:

  • appl0 — detailed diagnostics for metrics, their source and timezone, metadata, units normalization, output format, etc. Basically the whole backstage tour. ✨

👑 SEE ALSO 👑

PCPIntro(1), pmcd(1), pmchart(1), pmlogger(1), pmrep(1), PMAPI(3), strftime(3) and environ(7).

Go read them. All of them. Not optional, bestie. 📚💅

And that's the whole page, periodt. This one came to you courtesy of Performance Co-Pilot, filed under PMDUMPTEXT(1) — and ngl, there's no date stamped on this footer, so we're just gonna say iconic and timeless. 💖✨🎀🦋🌸

📦 where this page comes from