# pmlogdump

## NAME



           **pmlogdump** , **pmdumplog** - dump internal details of a performance
           metrics archive
    


## SYNOPSIS



           **pmlogdump**[**-adehIilLmMrstxzV?**]  [**-D** _debug_] [**-n** _pmnsfile_] [**-S**
           _starttime_] [**-T** _endtime_] [**-Z** _timezone_] _archive_ [_metricname_ ...]
           **pmlogdump**[**-v** _file_]
    


## DESCRIPTION



           **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 _archive_ and must have been
           previously created using pmlogger(1).  Alternatively _archive_ is
           the name of a directory that contains a set of PCP archives than
           could be opened with pmNewContext(3).
    
           Historically, **pmlogdump** was known as **pmdumplog** but the latter name
           is not consistent with the other PCP commands that operate on PCP
           archives, so **pmlogdump** is preferred, however **pmdumplog** is
           maintained for backwards compatibility.
    
           Normally **pmlogdump** operates on the distributed Performance Metrics
           Name Space (PMNS), however if the **-n** option is specified an
           alternative local PMNS is loaded from the file _pmnsfile_.
    
           If any _metricname_ arguments appear, the report will be restricted
           to information relevant to the named performance metrics.  If
           _metricname_ is a non-leaf node in the namespace (see PMNS(5)), then
           **pmlogdump** will recursively descend the archive's namespace and
           report on all leaf nodes.
    
           Command line options control the specific information to be
           reported.
    


## OPTIONS



           The available command line options are:
    
           **-a** , **--all**
                Report almost everything, i.e. the flags **-d** , **-i** , **-L** , **-m** , **-s**
                and **-t**.  The optional help text (-**h**) and label metadata
                strings (-**e**) are not reported by default.
    
           **-d** , **--descs**
                Display the metadata and descriptions for those performance
                metrics that appear at least once in the archive: see
                pmLookupDesc(3) for more details on the metadata describing
                metrics.  Metrics are reported in ascending Performance
                Metric Identifier (PMID) sequence.
    
           **-e** , **--labelsets**
                Display the label metadata if it is present in the archive.
                See pmLookupLabels(3) for more details on the label metadata
                hierarchy associated with metrics.
    
           **-h** , **--helptext**
                Display metric and instance domain help text if present in
                the archive.  See pmLookupText(3) for more details on the
                help text associated with metrics.
    
           **-i** , **--insts**
                Display the instance domains, and any variations in their
                instance members over the duration of the archive: see
                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.
    
           **-I** , **--on-disk-insts**
                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
                pmGetInDom(3) and related routines.  The on-disk format is
                only of interest when investigating the internal structure of
                PCP archives.
    
           **-l** , **--label**
                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.
    
           **-L** Like **-l** , just a little more verbose.
    
           **-m** , **--metrics**
                Print the values for the performance metrics from the
                archive.  This is the default display option.
    
                Metrics without an instance domain are reported as:
                  [_timestamp_] _metric-id_ (_metric-name_): **value1** _value2_
    
                Metrics with an instance domain are reported as:
                  [_timestamp_] _metric-id_ (_metric-name_):
                      **inst**[_internal-id_ **or** "_external-id_ "] **value1** _value2_
    
                The _timestamp_ is only reported for the first metric in a
                group of metrics sharing the same timestamp.
    
           **-M** , **--markrecs**
                If no _metricname_ is specified then _< mark>_ records are
                reported when they are found in the _archive_.  If _metricname_
                arguments are specified, then _< mark>_ records are not reported
                by default.  The **-M** option forces _< mark>_ records to be
                reported, even when _metricname_ arguments are specified.
    
                _< mark>_ records are inserted into a PCP archive by
                pmlogger(1), pmlogextract(1), and similar tools to indicate a
                temporal discontinuity in the time-series of metric values.
    
           **-n** _pmnsfile_ , **--namespace** =_pmnsfile_
                Load an alternative Performance Metrics Name Space (PMNS(5))
                from the file _pmnsfile_.
    
           **-r** , **--reverse**
                Process the archive in reverse order, from most recent to
                oldest recorded metric values.
    
           **-s** , **--sizes**
                Report the size in bytes of each physical record in the
                archive.
    
           **-S** _starttime_ , **--start** =_starttime_
                When using the **-m** option, the report will be restricted to
                those records logged at or after _starttime_.  Refer to
                PCPIntro(1) for a complete description of the syntax for
                _starttime_.
    
           **-t** Dump the temporal index that is used to provide accelerated
                access to large archive files.
    
                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.
    
           **-T** _endtime_ , **--finish** =_endtime_
                When using the **-m** option, the report will be restricted to
                those records logged before or at _endtime_.  Refer to
                PCPIntro(1) for a complete description of the syntax for
                _endtime_.
    
           **-v** _file_
                Verbose mode.  Dump the records from a physical archive file
                in hexadecimal format.  In this case _file_ is the name of a
                single file, usually a basename (as would otherwise appear as
                the _archive_ command line argument), concatenated with ``.''
                followed by one of **meta**(the metadata), **index**(the temporal
                index), or a digit (one of the volumes of metric values).
    
                Use of **-v** precludes the use of all other options and
                arguments.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-x** 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.
    
                A second **-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 _libpcp_.
    
                A third **-x** option will also report the timestamp in ``Epoch''
                format (seconds since 1970-01-01 00:00:00 UTC).
    
           **-z** , **--hostzone**
                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.
    
           **-Z** _timezone_ , **--timezone** =_timezone_
                By default, **pmlogdump** reports the time of day according to
                the local timezone on the system where **pmlogdump** is run.  The
                **-Z** option changes the timezone to _timezone_ in the format of
                the environment variable **TZ** as described in environ(7).
    
           **-?** , **--help**
                Display usage message and exit.
    


## FILES



           _$PCP_LOG_DIR/pmlogger/ <hostname>_
                Default directory for PCP archives containing performance
                metric values collected from the host _hostname_.
    


## 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(5).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    


* * *