PMLOGCOMPRESS(1)

NAME
pmlogcompress, pmlogdecompress - compress and decompress PCP archive files

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

DESCRIPTION
pmlogcompress and pmlogdecompress support the compression and decompression of the files that make up a Performance Co-Pilot (PCP) archive; refer to LOGARCHIVE(5) for an explanation of the various files that are components of a PCP archive.

The archive arguments may be either the name of a single file in a PCP archive or the basename of a PCP archive, as in the style generated by pmlogbasename(1). In the former case, pmlogcompress will compress (or pmlogdecompress will decompress) just that file, but in the latter case pmlogcompress will attempt to compress (or for pmlogdecompress to decompress) all the files that are part of the associated PCP archive.

For decompression the suffix of the name of each file associated with archive determines the decompression tool to be used.

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.

-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 if 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.

-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).

    The default value for limit is 4096.

-N, --show-me
    Do nothing, but show what commands would have been executed.

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

-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).

    dir must exist before pmlogdecompress is run.

-V, --verbose
    Increase verbosity.

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

NOTE
For most users pmlogcompress and pmlogdecompress will not be used directly because explicit compression and decompression of PCP archives is not required.

Rather, if archive compression is enabled, then this will be done indirectly from the PCP archive managements 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).

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.

The table below describes the variables and their equivalence to some of the command line options.
Variable | Command line option | Description
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 with just one 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
PCP_COMPRESS_ZSTD_ARGS | -A arg -f zstd | Command line arguments to be used with
PCP_COMPRESS_XZ_ARGS | -A arg -f xz | Command line arguments to be used with
PCP_COMPRESS_BZIP2_ARGS | -A arg -f bzip2 | Command line arguments to be used with
PCP_COMPRESS_GZIP_ARGS | -A arg -f gzip | Command line arguments to be used with

FILES
$PCP_SYSCONF_DIR/pmlogcompress/defaults
    default settings for variables used by pmlogcompress

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(4).

pmlogcompress has additional private variables with default values in $PCP_SYSCONF_DIR/pmlogcompress/defaults as described above.

SEE ALSO
PCPIntro(1), bzip2(1), gzip(1), pmlogbasename(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), pmlogger_rewrite(1), xz(1), zstd(1), PMAPI(3) and LOGARCHIVE(5).