PMLOGCOMPRESS(1)

📦
version 7.2.2 · 3 versions
, in arch rolling, fedora 43, fedora 44

💖 PMLOGCOMPRESS(1) — General Commands Manual 💖

okay bestie, sit down, hydrate, because we're about to talk about PCP archive compression and honestly? it's giving useful. this is the manual page for pmlogcompress and pmlogdecompress, two little icons that squash and unsquash the files that make up a Performance Co-Pilot (PCP) archive. 🫶

✨ NAME ✨

pmlogcompress, pmlogdecompress — compress and decompress PCP archive files. no cap, that's the whole job description. 💅

🌸 SYNOPSIS 🌸

pmlogcompress [-NV?] [-A arg] [-C conffile] [-c proglist] [-f prog] [-l
limit] [-o type] [-Z min] archive ...
pmlogdecompress [-NV?] [-t dir] archive ...

🦋 DESCRIPTION 🦋

so pmlogcompress and pmlogdecompress support the compression and decompression of the files that make up a Performance Co-Pilot (PCP) archive. if you're sitting there like "what even are the files in a PCP archive", bestie, go read LOGARCHIVE(5) — it explains every single file that's a component of a PCP archive. 📚

now, the archive arguments. they can be either:

  • the name of a single file in a PCP archive, or
  • the basename of a PCP archive — the style that pmlogbasename(1) generates.

in the first case, pmlogcompress will compress (or pmlogdecompress will decompress) just that one file. literally just that file. but in the second case, pmlogcompress will attempt to compress (or pmlogdecompress will attempt to decompress) all the files that are part of the associated PCP archive. the whole squad. 👑

for decompression, the suffix of the name of each file associated with archive determines the decompression tool to be used. the filename tells you the vibe, and you follow it. 🎀

💅 OPTIONS 💅

the available command line options are:

  • -A arg, --arg=arg — arg is used as an argument to the compression program. most likely useful with the -f option so that the choice of compression program is deterministic.

the processing of arg is not sophisticated, so embedded shell variables, escape characters, shell ``glob'' characters and white space should be avoided. 🙈

multiple -A options are allowed and all the arg arguments will be used. stack 'em up.

  • -C conffile, --config=conffile — as described below, variables that control the behaviour of pmlogcompress are defined in the configuration file $PCP_SYSCONF_DIR/pmlogcompress/defaults. the -C option allows for an alternate configuration file, conffile, to be used.
  • -c proglist, --command=proglist — depending on other command line options, and the availability of installed compression programs, the choice of program when compressing may vary. the -c option allows a list of compression programs to be provided, either with multiple -c options and/or by separating program names in proglist by a colon, in the style of the shell's $PATH notation.

the default value for proglist is zstd:xz:bzip2:gzip. periodt. 💖

  • -f prog, --use=prog — if only one program is to be considered for compression then this may be specified using the -f option. the effect is the same as if only one -c option was used and proglist contained exactly one program name, namely prog.
  • -l limit, --lower-limit=limit — when compressing, do not consider files smaller than limit (bytes). tiny files, we're leaving you alone.

the default value for limit is 4096.

  • -N, --show-me — do nothing, but show what commands would have been executed. it's the dress rehearsal. nothing actually happens, you just get to peek. 👀
  • -o type, --optimize=type — when compressing the -o option will try to pick the compression program from proglist (see the -c option above) that does the ``best'' job, where type may be space to choose the compression program that produces the smallest output file, or time to choose the compression program that uses the least CPU time.

if archive is an archive basename then the largest of the files that are part of the associated PCP archive is selected for the test, else archive will be used for the test.

use of this option means each of the selected archive files will be compressed multiple times, so it is likely that -o would be used in experiments with -N (and possibly -V) to determine the best compression tool for the local environment and PCP archives. science! 🔥

  • -t dir, --dir=dir — when decompressing, any compressed files will (by default) be replaced by their decompressed equivalent. the -t option changes this behavior to create a duplicate, uncompressed archive in the dir directory.

if archive is a single file, then only that file is decompressed into dir, but if archive is an archive basename then all of the files of archive will be copied, and possibly decompressed, into dir.

if a file is not compressed, then an attempt will first be made to create a hard link in dir with ln(1) and if this fails then a copy is made with cp(1).

warning bestie: dir must exist before pmlogdecompress is run. it will not make it for you. it's not your mom. 😭
  • -V, --verbose — increase verbosity. more words, more insight, more slay.
  • -Z min, --min-zstd-size=min — xz(1) produces smaller compressed files for small input files, but at some point the input file becomes large enough that zstd(1) produces smaller compressed files and zstd is typically much faster.

when both xz and xstd are in consideration (see the -c option above), then the -Z option allows the user to tune where the xz to zstd cut-over happens; input files smaller than min (in bytes) will be compressed with xz else zstd will be used.

the default value for min is 52428800 (50MiB).

  • -?, --help — display usage message and exit. the classic. 🎀

💜 NOTE 💜

for most users pmlogcompress and pmlogdecompress will not be used directly, because explicit compression and decompression of PCP archives is not required. it just happens for you, bestie. the magic is behind the curtain. ✨

rather, if archive compression is enabled, then this will be done indirectly from the PCP archive management scripts pmlogger_check(1), pmlogger_daily(1) and pmlogger_rewrite (1) using pmlogcompress.

decompression is handled transparently during archive replay by the routines that implement the Performance Metrics Programming Interface (PMAPI). you don't even have to ask. 💖

🌈 VARIABLES 🌈

pmlogcompress uses a number of variables that can be used to customize the behaviour. defaults are defined in the configuration file $PCP_SYSCONF_DIR/pmlogcompress/defaults, but these can be over-ridden by setting variables of the same name in the environment. and some command line options over-ride variables set in either the configuration file or the environment. it's a whole hierarchy, iykyk. 👑

the list below describes the variables and their equivalence to some of the command line options.

  • PCP_COMPRESS_PROGS
    • -c proglist — a colon separated list of programs to be considered in turn. if only one program appears in the list, then all compression will consider using only that program.
    • -f prog — short-hand for a proglist with just one prog in it.
  • PCP_COMPRESS_MIN_FILESIZE
    • -l limit — archive files smaller than this will never be compressed.
  • PCP_COMPRESS_ZSTD_MIN_FILESIZE
    • -f prog — archive files smaller than this will never be compressed with zstd(1).
  • PCP_COMPRESS_ZSTD_ARGS
    • -A arg -f zstd — command line arguments to be used with zstd(1).
  • PCP_COMPRESS_XZ_ARGS
    • -A arg -f xz — command line arguments to be used with xz(1).
  • PCP_COMPRESS_BZIP2_ARGS
    • -A arg -f bzip2 — command line arguments to be used with bzip2(1).
  • PCP_COMPRESS_GZIP_ARGS
    • -A arg -f gzip — command line arguments to be used with gzip(1).

🎀 FILES 🎀

  • $PCP_SYSCONF_DIR/pmlogcompress/defaults — default settings for variables used by pmlogcompress.

🌸 PCP ENVIRONMENT 🌸

okay so here's the tea about how PCP finds its stuff 🫶 — every environment variable that starts with the prefix PCP_ is what parameterizes the file and directory names that PCP uses. like, that's the whole naming system, it's giving very "everything is configurable" ✨

on each installation, the file /etc/pcp.conf holds the local values for all of those variables. so that's where your machine's actual answers live 💅

and if you wanna be extra and use a different config file? the $PCP_CONF variable is literally right there for exactly that — you can use it to specify an alternative configuration file, as described in pcp.conf(4). main character energy fr fr 👑

also, pmlogcompress has its own additional private variables, and their default values hang out in $PCP_SYSCONF_DIR/pmlogcompress/defaults, as described above ⬆️ (yes bestie, scroll up, it's all there 💖)

🔥 SEE ALSO 🔥

go read these next, they're all iconic in their own way 😌:

and that's the whole page, bestie, we ate and left absolutely no crumbs 🎀 this one comes to you straight from Performance Co-Pilot (PCP) — the PMLOGCOMPRESS(1) page, delivered with love 💖 go compress something and slay ✨🦋

📦 where this page comes from