NAME
pmlogextract - reduce, extract, concatenate and merge Per
formance Co-Pilot archives
SYNOPSIS
$PCP_BINADM_DIR/pmlogextract [-wz] [-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 sam
ples] [-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 con
trolled 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 pmlo
gextract, 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 sec
tion.
-n pmnsfile
Normally pmlogextract operates on the Performance
Metrics Name Space (PMNS) from input, however if
the -n option is specified an alternative local
-S starttime
Define the start of a time window to restrict the
samples retrieved or specify a ``natural'' align
ment of the output sample times; refer to PCPIn
tro(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 win
dow 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 indi
cate 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 vari
able 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.
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 Per
formance Metrics Namespace (PMNS, see pmns(4)). If a met
ric 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 associ
ated 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 physi
cal 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),
pcp.conf(4) and pcp.env(4).
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 sud
denly 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.pmlog
ger.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 cre
ated, and have no significance once recording has fin
ished.
Man(1) output converted with
man2html