Linux Certif

Toute la documentation sur la certification Linux LPI

pmlogextract

NAME

pmlogextract - reduce, extract, concatenate and merge Performance Co-Pilot archives

SYNOPSIS

$PCP_BINADM_DIR/pmlogextract [-dwz] [-c configfile] [-n pmnsfile] [-S starttime] [-s samples] [-T endtime] [-v volsamples] [-Z timezone] input [...] output

On IRIX:

$PCP_BINADM_DIR/pmlogmerge [-z] [-S starttime] [-s samples] [-T endtime] [-v volsamples] [-Z timezone] input [...] output

DESCRIPTION

pmlogextract reads one or more Performance Co-Pilot (PCP) archive logs identified by input and creates a temporally merged and/or reduced PCP archive log in output. The nature of merging is controlled by the number of input archive logs, while the nature of data reduction is controlled by the command line arguments. The input(s) must be PCP archive logs created by pmlogger(1).

pmlogmerge provides a subset of the capabilities of pmlogextract, namely reading one or more PCP archive logs identified by input and creating a temporally merged PCP archive log in output. pmlogmerge is deprecated and is provided on Irix for backwards-compatibility.

If only one input is specified, then the default behavior simply copies the input PCP archive log, into the output PCP archive log. When two or more PCP archive logs are specified as input, the logs are merged (or concatenated) and written to output.

COMMAND LINE OPTIONS

The command line options for pmlogextract are as follows:

-c configfile

Extract only the metrics specified in configfile from the input PCP archive log(s). The configfile syntax accepted by pmlogextract is explained in more detail in the Configuration File Syntax section.

-d

Desperate mode. Normally if a fatal error occurs, all trace of the partially written PCP archive output is removed. With the -d option, the output archive is not removed.

-n pmnsfile

Normally pmlogextract operates on the Performance Metrics Name Space (PMNS) from input, however if the -n option is specified an alternative local PMNS is loaded from the file pmnsfile.

-S starttime

Define the start of a time window to restrict the samples retrieved or specify a ``natural'' alignment of the output sample times; refer to PCPIntro(1). See also the -w option.

-s samples

The argument samples defines the number of samples to be written to output. If samples is 0 or -s is not specified, pmlogextract will sample until the end of the PCP archive, or the end of the time window as specified by -T, whichever comes first. The -s option will override the -T option if it occurs sooner.

-T endtime

Define the termination of a time window to restrict the samples retrieved or specify a ``natural'' alignment of the output sample times; refer to PCPIntro(1). See also the -w option.

The output archive log is potentially a multi-volume data set, and the -v option causes pmlogextract to start a new volume after volsamples log records have been written to the archive.

-w

Where -S and -T specify a time window within the same day, the -w flag will cause the data within the time window to be extracted, for every day in the archive. For example, the options -w -S @11:00 -T @15:00 specify that pmlogextract should include archive log records only for the periods from 11am to 3pm on each day. When -w is used, the output archive log will contain ``mark'' records to indicate the temporal discontinuity between the end of one time window and the start of the next.

-Z timezone

Use timezone when displaying the date and time. Timezone is in the format of the environment variable TZ as described in environ(5).

-z

Use the local timezone of the host from the input archive logs. The default is to initially use the timezone of the local host.

CONFIGURATION FILE SYNTAX

The configfile contains metrics of interest, listed one per line. Instances may also be specified, but they are optional. The format for each metric name is

        metric [[instance[,instance...]]]

where metric may be a leaf or a non-leaf node in the Performance Metrics Namespace (PMNS, see pmns(4)). If a metric refers to a non-leaf node in the PMNS, pmlogextract will recursively descend the PMNS and include all metrics corresponding to descendent leaf nodes. Instances are optional, and may be specified as a list of one or more space (or comma) separated names, numbers or strings. Elements in the list that are numbers are assumed to be external instance identifiers - see pmGetInDom(3) for more information. If no instances are given, then the logging specification is applied to all instances of the associated metric(s).

CONFIGURATION FILE EXAMPLE

This is an example of a valid configfile:

        #
        # config file for pmlogextract
        #

        kernel.all.cpu
        kernel.percpu.cpu.sys ["cpu0","cpu1"]
        disk.dev ["dks0d1"]

FILES

For each of the input and output archives, several physical files are used.

archive.meta

metadata (metric descriptions, instance domains, etc.) for the archive log

archive.0

initial volume of metrics values (subsequent volumes have suffixes 1, 2, ...)

archive.index

temporal index to support rapid random access to the other files in the archive log.

 

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

SEE ALSO

PCPIntro(1), pmdumplog(1), pmlc(1), pmlogger(1), pmlogreduce(1), pcp.conf(4) and pcp.env(4).

DIAGNOSTICS

All error conditions detected by pmlogextract are reported on stderr with textual (if sometimes terse) explanation.

Should one of the input archive logs be corrupted (this can happen if the pmlogger instance writing the log suddenly dies), then pmlogextract will detect and report the position of the corruption in the file, and any subsequent information from that archive log will not be processed.

If any error is detected, pmlogextract will exit with a non-zero status.

CAVEATS

pmlogmerge has been retained on Irix to provide backwards compatibility with earlier PCP releases, however, use of pmlogextract is encouraged in preference to pmlogmerge, and pmlogmerge may not be supported in future PCP releases.

The preamble metrics (pmcd.pmlogger.archive, pmcd.pmlogger.host, and pmcd.pmlogger.port), which are automatically recorded by pmlogger at the start of the archive, may not be present in the archive output by pmlogextract. These metrics are only relevant while the archive is being created, and have no significance once recording has finished.