'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMLOGDUMP 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogdump\f1,
\f3pmdumplog\f1 \- dump internal details of a performance metrics archive
.SH SYNOPSIS
\f3pmlogdump\f1
[\f3\-adehIilLmMrstxzV?\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-S\f1 \f2starttime\f1]
[\f3\-T\f1 \f2endtime\f1]
[\f3\-Z\f1 \f2timezone\f1]
\f2archive\f1
[\f2metricname\f1 ...]
.br
\f3pmlogdump\f1
[\f3\-v\f1 \f2file\f1]
.SH DESCRIPTION
.B pmlogdump
dumps assorted control, metadata, index and state information from
the files of a Performance Co-Pilot (PCP) archive.
The archive has the base name
.I archive
and must have been previously created using
.BR pmlogger (1).
Alternatively
.I archive
is the name of a directory that contains a set of PCP archives
than could be opened with
.BR pmNewContext (3).
.PP
Historically,
.B pmlogdump
was known as
.B pmdumplog
but the latter name is not consistent with the other PCP commands
that operate on PCP archives, so
.B pmlogdump
is preferred, however
.B pmdumplog
is maintained for backwards compatibility.
.PP
Normally
.B pmlogdump
operates on the distributed Performance Metrics Name Space (PMNS), however
if the
.B \-n
option is specified an alternative local PMNS is loaded
from the file
.IR pmnsfile .
.PP
If any
.I metricname
arguments appear, the report will be restricted to information relevant
to the named performance metrics.
If
.I metricname
is a non-leaf node in the namespace (see \c
.BR PMNS (5)),
then
.B pmlogdump
will recursively descend the archive's namespace and report on all leaf nodes.
.PP
Command line options control the specific information to be reported.
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-a\fR, \fB\-\-all\fR
Report almost everything, i.e. the flags
.BR \-d ,
.BR \-i ,
.BR \-L ,
.BR \-m ,
.BR \-s
and
.BR \-t .
The optional help text (\-\f3h\f1) and label metadata
strings (\-\f3e\f1) are not reported by default.
.TP
\fB\-d\fR, \fB\-\-descs\fR
Display the metadata and descriptions for those performance metrics
that appear at least once in the archive:
see
.BR pmLookupDesc (3)
for more details on the metadata describing metrics.
Metrics are reported in ascending
Performance Metric Identifier (PMID) sequence.
.TP
\fB\-e\fR, \fB\-\-labelsets\fR
Display the label metadata if it is present in the archive.
See
.BR pmLookupLabels (3)
for more details on the label metadata hierarchy associated with metrics.
.TP
\fB\-h\fR, \fB\-\-helptext\fR
Display metric and instance domain help text if present in the archive.
See
.BR pmLookupText (3)
for more details on the help text associated with metrics.
.TP
\fB\-i\fR, \fB\-\-insts\fR
Display the instance domains, and any variations in their instance
members over the duration of the archive: see
.BR pmGetInDom (3)
for more details on instance domains.
Instance domains are reported in ascending
Instance Domain Identifier sequence and then ascending time for
each set of observed instance members within an instance domain.
.TP
\fB\-I\fR, \fB\-\-on-disk-insts\fR
Display the on-disk instance domains, which may use a different format
and encoding than the one visible above the
Performance Metrics Programming Interface (PMAPI)
when using
.BR pmGetInDom (3)
and related routines.
The on-disk format is only of interest when investigating the internal
structure of PCP archives.
.TP
\fB\-l\fR, \fB\-\-label\fR
Dump the archive label, showing the archive format version,
the time and date for the start and (current) end of the archive, and
the host from which the performance metrics values were collected.
.TP
\fB\-L\fR
Like
.BR \-l ,
just a little more verbose.
.TP
\fB\-m\fR, \fB\-\-metrics\fR
Print the values for the performance metrics from the archive.
This is the default display option.
.RS +5n
.P
Metrics without an instance domain are reported as:
.br
.ti +2n
[\fItimestamp\fR] \fImetric-id\fR (\fImetric-name\fR): \fBvalue1\fR \fIvalue2\fR
.P
Metrics with an instance domain are reported as:
.br
.ti +2n
[\fItimestamp\fR] \fImetric-id\fR (\fImetric-name\fR):
.br
.ti +6n
\fBinst\fR [\fIinternal-id\fR \fBor\fR "\fIexternal-id\fR"]
\fBvalue1\fR \fIvalue2\fR
.P
The \fItimestamp\fR is only reported for the first metric in
a group of metrics sharing the same timestamp.
.RE
.TP
\fB\-M\fR, \fB\-\-markrecs\fR
If no
.I metricname
is specified then
.I <mark>
records are reported when they are found in the
.IR archive .
If
.I metricname
arguments are specified, then
.I <mark>
records are not reported by default.
The
.B \-M
option forces
.I <mark>
records to be reported, even when
.I metricname
arguments are specified.
.RS +5n
.P
.I <mark>
records are inserted into a PCP archive by
.BR pmlogger (1),
.BR pmlogextract (1),
and similar tools to indicate a temporal discontinuity in the
time-series of metric values.
.RE
.TP
\fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR
Load an alternative Performance Metrics Name Space
.RB ( PMNS (5))
from the file
.IR pmnsfile .
.TP
\fB\-r\fR, \fB\-\-reverse\fR
Process the archive in reverse order, from most recent to oldest
recorded metric values.
.TP
\fB\-s\fR, \fB\-\-sizes\fR
Report the size in bytes of each physical record in the archive.
.TP
\fB\-S\fR \fIstarttime\fR, \fB\-\-start\fR=\fIstarttime\fR
When using the
.B \-m
option, the report will be restricted to those records logged at or after
.IR starttime .
Refer to
.BR PCPIntro (1)
for a complete description of the syntax for
.IR starttime .
.TP
\fB\-t\fR
Dump the temporal index that is used to provide accelerated access
to large archive files.
.RS
.PP
The integrity of the index will also be checked.
If the index is found to be corrupted, the ``*.index'' file can be renamed
or removed and the archive will still be accessible, however retrievals
may take longer without the index.
Note however that a corrupted temporal index is usually indicative of a
deeper malaise that may infect all files in a PCP archive.
.RE
.TP
\fB\-T\fR \fIendtime\fR, \fB\-\-finish\fR=\fIendtime\fR
When using the
.B \-m
option, the report will be restricted to those records logged before or at
.IR endtime .
Refer to
.BR PCPIntro (1)
for a complete description of the syntax for
.IR endtime .
.TP
\fB\-v\fR \fIfile\fR
Verbose mode.
Dump the records from a physical archive file in hexadecimal format.
In this
case
.I file
is the name of a single file, usually a basename (as would otherwise
appear as the
.I archive
command line argument), concatenated with ``.'' followed by one of
.B meta
(the metadata),
.B index
(the temporal index), or
a digit (one of the volumes of metric values).
.sp 1.5v
Use of
.B \-v
precludes the use of all other options and arguments.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version number and exit.
.TP
\fB\-x\fR
Extended timestamp reporting format that includes the day of the week, day of the month,
month and year in addition to the (default) hours, minutes and seconds time.
This is useful for archives that span multiple days.
.RS +5n
.PP
A second
.B -x
option will also report the timestamp as an offset from the start of the
archive in units of seconds.
This is useful in conjunction with debug diagnostics from the
archive handling routines in
.IR libpcp .
.PP
A third
.B -x
option will also report the timestamp in ``Epoch'' format (seconds
since 1970-01-01 00:00:00 UTC).
.RE
.TP
\fB\-z\fR, \fB\-\-hostzone\fR
Change the timezone to the local timezone at the
host that is the source of the performance metrics, as specified in
the label record of the archive.
.TP
\fB\-Z\fR \fItimezone\fR, \fB\-\-timezone\fR=\fItimezone\fR
By default,
.B pmlogdump
reports the time of day according to the local timezone on the
system where
.B pmlogdump
is run.
The
.B \-Z
option changes the timezone to
.I timezone
in the format of the environment variable
.B TZ
as described in
.BR environ (7).
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH FILES
.TP 5
.I $PCP_LOG_DIR/pmlogger/<hostname>
Default directory for PCP archives containing performance
metric values collected from the host
.IR hostname .
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmlogcheck (1),
.BR pmlogextract (1),
.BR pmlogger (1),
.BR pmlogger_check (1),
.BR pmlogger_daily (1),
.BR pmloglabel (1),
.BR PMAPI (3),
.BR pmGetInDom (3),
.BR pmLookupDesc (3),
.BR pmNewContext (3),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR PMNS (5).

.\" control lines for scripts/man-spell
.\" +ok+ pmdumplog { old name ref }