1PMLOGDUMP(1) General Commands Manual PMLOGDUMP(1)
2
6 pmlogdump, pmdumplog - dump internal details of a performance metrics
7 archive
8
10 pmlogdump [-adehIilLmMrstxzV?] [-n pmnsfile] [-S starttime] [-T end‐
11 time] [-Z timezone] archive [metricname ...]
12 pmlogdump [-v file]
13
15 pmlogdump dumps assorted control, metadata, index and state information
16 from the files of a Performance Co-Pilot (PCP) archive. The archive
17 has the base name archive and must have been previously created using
18 pmlogger(1).
19 Historically, pmlogdump was known as pmdumplog but the latter name is
21 not consistent with the other PCP commands that operate on PCP ar‐
22 chives, so pmlogdump is preferred, however pmdumplog is maintained for
23 backwards compatibility.
24 Normally pmlogdump operates on the distributed Performance Metrics Name
26 Space (PMNS), however if the -n option is specified an alternative lo‐
27 cal PMNS is loaded from the file pmnsfile.
28 If any metricname arguments appear, the report will be restricted to
30 information relevant to the named performance metrics. If metricname
31 is a non-leaf node in the namespace (see PMNS(5)), then pmlogdump will
32 recursively descend the archive's namespace and report on all leaf
33 nodes.
34 Command line options control the specific information to be reported.
36
38 The available command line options are:
39 -a, --all
41 Report almost everything, i.e. the flags -d, -i, -L, -m, -s and
42 -t. The optional help text (-h) and label metadata strings (-e)
43 are not reported by default.
44 -d, --descs
46 Display the metadata and descriptions for those performance met‐
47 rics that appear at least once in the archive: see pmLookupDesc(3)
48 for more details on the metadata describing metrics.
49 -e, --labelsets
51 Display the label metadata if it is present in the archive. See
52 pmLookupLabels(3) for more details on the label metadata hierarchy
53 associated with metrics.
54 -h, --helptext
56 Display metric and instance domain help text if present in the ar‐
57 chive. See pmLookupText(3) for more details on the help text as‐
58 sociated with metrics.
59 -i, --insts
61 Display the instance domains, and any variations in their instance
62 members over the duration of the archive: see pmGetInDom(3) for
63 more details on instance domains.
64 -I, --on-disk-insts
66 Display the on-disk instance domains, which may use a different
67 format and encoding than the one visible above the Performance
68 Metrics Programming Interface (PMAPI) when using pmGetInDom(3) and
69 related routines. The on-disk format is only of interest when in‐
70 vestigating the internal structure of PCP archives.
71 -l, --label
73 Dump the archive label, showing the archive format version, the
74 time and date for the start and (current) end of the archive, and
75 the host from which the performance metrics values were collected.
76 -L Like -l, just a little more verbose.
78 -m, --metrics
80 Print the values for the performance metrics from the archive.
81 This is the default display option.
82 Metrics without an instance domain are reported as:
84 [timestamp] metric-id (metric-name): value1 value2
85 Metrics with an instance domain are reported as:
87 [timestamp] metric-id (metric-name):
88 inst [internal-id or "external-id"] value1 value2
89 The timestamp is only reported for the first metric in a group of
91 metrics sharing the same timestamp.
92 -M, --markrecs
94 If no metricname is specified then <mark> records are reported
95 when they are found in the archive. If metricname arguments are
96 specified, then <mark> records are not reported by default. The
97 -M option forces <mark> records to be reported, even when metric‐
98 name arguments are specified.
99 <mark> records are inserted into a PCP archive by pmlogger(1), pm‐
101 logextract(1), and similar tools to indicate a temporal disconti‐
102 nuity in the time-series of metric values.
103 -n pmnsfile, --namespace=pmnsfile
105 Load an alternative Performance Metrics Name Space (PMNS(5)) from
106 the file pmnsfile.
107 -r, --reverse
109 Process the archive in reverse order, from most recent to oldest
110 recorded metric values.
111 -s, --sizes
113 Report the size in bytes of each physical record in the archive.
114 -S starttime, --start=starttime
116 When using the -m option, the report will be restricted to those
117 records logged at or after starttime. Refer to PCPIntro(1) for a
118 complete description of the syntax for starttime.
119 -t Dump the temporal index that is used to provide accelerated access
121 to large archive files.
122 The integrity of the index will also be checked. If the index is
124 found to be corrupted, the ``*.index'' file can be renamed or re‐
125 moved and the archive will still be accessible, however retrievals
126 may take longer without the index. Note however that a corrupted
127 temporal index is usually indicative of a deeper malaise that may
128 infect all files in a PCP archive.
129 -T endtime, --finish=endtime
131 When using the -m option, the report will be restricted to those
132 records logged before or at endtime. Refer to PCPIntro(1) for a
133 complete description of the syntax for endtime.
134 -v file
136 Verbose mode. Dump the records from a physical archive file in
137 hexadecimal format. In this case file is the name of a single
138 file, usually a basename (as would otherwise appear as the archive
139 command line argument), concatenated with ``.'' followed by one of
140 meta (the metadata), index (the temporal index), or a digit (one
141 of the volumes of metric values).
142 Use of -v precludes the use of all other options and arguments.
144 -V, --version
146 Display version number and exit.
147 -x Extended timestamp reporting format that includes the day of the
149 week, day of the month, month and year in addition to the (de‐
150 fault) hours, minutes and seconds time. This is useful for ar‐
151 chives that span multiple days.
152 A second -x option will also report the timestamp as an offset
154 from the start of the archive in units of seconds. This is useful
155 in conjunction with debug diagnostics from the archive handling
156 routines in libpcp.
157 A third -x option will also report the timestamp in ``Epoch'' for‐
159 mat (seconds since 1970-01-01 00:00:00 UTC).
160 -z, --hostzone
162 Change the timezone to the local timezone at the host that is the
163 source of the performance metrics, as specified in the label
164 record of the archive.
165 -Z timezone, --timezone=timezone
167 By default, pmlogdump reports the time of day according to the lo‐
168 cal timezone on the system where pmlogdump is run. The -Z option
169 changes the timezone to timezone in the format of the environment
170 variable TZ as described in environ(7).
171 -?, --help
173 Display usage message and exit.
174
176 $PCP_LOG_DIR/pmlogger/<hostname>
177 Default directory for PCP archives containing performance metric
178 values collected from the host hostname.
179
181 Environment variables with the prefix PCP_ are used to parameterize the
182 file and directory names used by PCP. On each installation, the file
183 /etc/pcp.conf contains the local values for these variables. The
184 $PCP_CONF variable may be used to specify an alternative configuration
185 file, as described in pcp.conf(5).
186
188 PCPIntro(1), pmlogcheck(1), pmlogger(1), pmlogger_check(1), pmlog‐
189 ger_daily(1), pmloglabel(1), pmlogextract(1), PMAPI(3), pmGetInDom(3),
190 pmLookupDesc(3), pcp.conf(5), pcp.env(5) and PMNS(5).
191Performance Co-Pilot PCP PMLOGDUMP(1)