1PMLOGREWRITE(1) General Commands Manual PMLOGREWRITE(1)
2
3
4
6 pmlogrewrite - rewrite Performance Co-Pilot archives
7
9 $PCP_BINADM_DIR/pmlogrewrite [-Cdiqsvw?] [-c config] [-V version] in‐
10 log [outlog]
11
13 pmlogrewrite reads a set of Performance Co-Pilot (PCP) archive logs
14 identified by inlog and creates a PCP archive log in outlog. Under
15 normal usage, the -c option will be used to nominate a configuration
16 file or files that contains specifications (see the REWRITING RULES
17 SYNTAX section below) that describe how the data and metadata from in‐
18 log should be transformed to produce outlog.
19
20 The typical uses for pmlogrewrite would be to accommodate the evolution
21 of Performance Metric Domain Agents (PMDAs) where the names, metadata
22 and semantics of metrics and their associated instance domains may
23 change over time, e.g. promoting the type of a metric from a 32-bit to
24 a 64-bit integer, or renaming a group of metrics. Refer to the EXAM‐
25 PLES section for some additional use cases.
26
27 pmlogrewrite is most useful where PMDA changes, or errors in the pro‐
28 duction environment, result in archives that cannot be combined with
29 pmlogextract(1). By pre-processing the archives with pmlogrewrite the
30 resulting archives may be able to be merged with pmlogextract(1).
31
32 The input inlog must be a set of PCP archive logs created by pmlog‐
33 ger(1), or possibly one of the tools that read and create PCP archives,
34 e.g. pmlogextract(1) and pmlogreduce(1). inlog is a comma-separated
35 list of names, each of which may be the base name of an archive or the
36 name of a directory containing one or more archives.
37
38 If no -c option is specified, then the default behavior simply creates
39 outlog as a copy of inlog. This is a little more complicated than
40 cat(1), as each PCP archive is made up of several physical files.
41
42 While pmlogrewrite may be used to repair some data consistency issues
43 in PCP archives, there is also a class of repair tasks that cannot be
44 handled by pmlogrewrite and pmloglabel(1) may be a useful tool in these
45 cases.
46
48 The available command line options are:
49
50 -c config, --config=config
51 If config is a file or symbolic link, read and parse rewriting
52 rules from there. If config is a directory, then all of the files
53 or symbolic links in that directory (excluding those beginning
54 with a period ``.'') will be used to provide the rewriting rules.
55 Multiple -c options are allowed.
56
57 -C, --check
58 Parse the rewriting rules and quit. outlog is not created. When
59 -C is specified, this also sets -v and -w so that all warnings and
60 verbose messages are displayed as config is parsed.
61
62 -d, --desperate
63 Desperate mode. Normally if a fatal error occurs, all trace of
64 the partially written PCP archive outlog is removed. With the -d
65 option, the partially created outlog archive log is not removed.
66
67 -i Rather than creating outlog, inlog is rewritten in place when the
68 -i option is used. A new archive is created using temporary file
69 names and then renamed to inlog in such a way that if any errors
70 (not warnings) are encountered, inlog remains unaltered.
71
72 -q, --quick
73 Quick mode, where if there are no rewriting actions to be per‐
74 formed (none of the global data, instance domains or metrics from
75 inlog will be changed), then pmlogrewrite will exit (with status
76 0, so success) immediately after parsing the configuration file(s)
77 and outlog is not created.
78
79 -s, --scale
80 When the ``units'' of a metric are changed, if the dimension in
81 terms of space, time and count is unaltered, then the scaling fac‐
82 tor is being changed, e.g. BYTE to KBYTE, or MSEC-1 to USEC-1, or
83 the composite MBYTE.SEC-1 to KBYTE.USEC-1. The motivation may be
84 (a) that the original metadata was wrong but the values in inlog
85 are correct, or (b) the metadata is changing so the values need to
86 change as well. The default pmlogrewrite behaviour matches case
87 (a). If case (b) applies, then use the -s option and the values
88 of all the metrics with a scale factor change in each result will
89 be rescaled. For finer control over value rescaling refer to the
90 RESCALE option for the UNITS clause of the metric rewriting rule
91 described below.
92
93 -v, --verbose
94 Enable verbose mode.
95
96 -V version, --version=version
97 Specifies the version of the output PCP archive being produced.
98 Currently only version 2 archive format is supported.
99
100 -w, --warnings
101 Emit warnings. Normally pmlogrewrite remains silent for any warn‐
102 ing that is not fatal and it is expected that for a particular ar‐
103 chive, some (or indeed, all) of the rewriting specifications may
104 not apply. For example, changes to a PMDA may be captured in a
105 set of rewriting rules, but a single archive may not contain all
106 of the modified metrics nor all of the modified instance domains
107 and/or instances. Because these cases are expected, they do not
108 prevent pmlogrewrite executing, and rules that do not apply to in‐
109 log are silently ignored by default. Similarly, some rewriting
110 rules may involve no change because the metadata in inlog already
111 matches the intent of the rewriting rule to correct data from a
112 previous version of a PMDA. The -w flag forces warnings to be
113 emitted for all of these cases.
114
115 -?, --help
116 Display usage message and exit.
117
118 The argument outlog is required in all cases, except when -i is speci‐
119 fied.
120
122 A configuration file contains zero or more rewriting rules as defined
123 below.
124
125 Keywords and special punctuation characters are shown below in
126 bolditalic font and are case-insensitive, so METRIC, metric and Metric
127 are all equivalent in rewriting rules.
128
129 The character ``#'' introduces a comment and the remainder of the line
130 is ignored. Otherwise the input is relatively free format with op‐
131 tional white space (spaces, tabs or newlines) between lexical items in
132 the rules.
133
134 A global rewriting rule has the form:
135
136 GLOBAL { globalspec ... }
137
138 where globalspec is zero or more of the following clauses:
139
140 HOSTNAME -> hostname
141
142 Modifies the label records in the outlog PCP archive, so that
143 the metrics will appear to have been collected from the host
144 hostname.
145
146 TIME -> delta
147
148 Both metric values and the instance domain metadata in a PCP
149 archive carry timestamps. This clause forces all the time‐
150 stamps to be adjusted by delta, where delta is an optional sign
151 ``+'' (the default) or ``-'', an optional number of hours fol‐
152 lowed by a colon ``:'', an optional number of minutes followed
153 by a colon ``:'', a number of seconds, an optional fraction of
154 seconds following a period ``.''. The simplest example would
155 be ``30'' to increase the timestamps by 30 seconds. A more
156 complex example would be ``-23:59:59.999'' to move the time‐
157 stamps backwards by one millisecond less than one day.
158
159 TZ -> "timezone"
160
161 Modifies the label records in the outlog PCP archive, so that
162 the metrics will appear to have been collected from a host with
163 a local timezone of timezone. timezone must be enclosed in
164 quotes, and should conform to the valid timezone syntax rules
165 for the local platform.
166
167 An indom rewriting rule modifies an instance domain and has the form:
168
169 INDOM domain.serial { indomspec ... }
170
171 where domain and serial identify one or more existing instance domains
172 from inlog - typically domain would be an integer in the range 1 to 510
173 and serial would be an integer in the range 0 to 4194304.
174
175 As a special case serial could be an asterisk ``*'' which means the
176 rule applies to every instance domain with a domain number of domain.
177
178 If a designated instance domain is not in inlog the rule has no effect.
179
180 The indomspec is zero or more of the following clauses:
181
182 INAME "oldname" -> "newname"
183
184 The instance identified by the external instance name oldname
185 is renamed to newname. Both oldname and newname must be en‐
186 closed in quotes.
187
188 As a special case, the new name may be the keyword DELETE (with
189 no quotes), and then the instance oldname will be expunged from
190 outlog which removes it from the instance domain metadata and
191 removes all values of this instance for all the associated met‐
192 rics.
193
194 If the instance names contain any embedded spaces then special
195 care needs to be taken in respect of the PCP instance naming
196 rule that treats the leading non-space part of the instance
197 name as the unique portion of the name for the purposes of
198 matching and ensuring uniqueness within an instance domain, re‐
199 fer to pmdaInstance(3) for a discussion of this issue.
200
201 As an illustration, consider the hypothetical instance domain
202 for a metric which contains 2 instances with the following
203 names:
204 red
205 eek urk
206
207 Then some possible INAME clauses might be:
208
209 "eek" -> "yellow like a flower"
210 Acceptable, oldname "eek" matches the "eek urk" in‐
211 stance.
212
213 "red" -> "eek"
214 Error, newname "eek" matches the existing "eek urk"
215 instance.
216
217 "eek urk" -> "red of another hue"
218 Error, newname "red of another hue" matches the ex‐
219 isting "red" instance.
220
221 INDOM -> newdomain.newserial
222
223 Modifies the metadata for the instance domain and every metric
224 associated with the instance domain. As a special case, newse‐
225 rial could be an asterisk ``*'' which means use serial from the
226 indom rewriting rule, although this is most useful when serial
227 is also an asterisk. So for example:
228 indom 29.* { indom -> 109.* }
229 will move all instance domains from domain 29 to domain 109.
230
231 INDOM -> DUPLICATE newdomain.newserial
232
233 A special case of the previous INDOM clause where the instance
234 domain is a duplicate copy of the domain.serial instance domain
235 from the indom rewriting rule, and then any mapping rules are
236 applied to the copied newdomain.newserial instance domain.
237 This is useful when a PMDA is split and the same instance do‐
238 main needs to be replicated for domain domain and domain newdo‐
239 main. So for example if the metrics foo.one and foo.two are
240 both defined over instance domain 12.34, and foo.two is moved
241 to another PMDA using domain 27, then the following rewriting
242 rules could be used:
243 indom 12.34 { indom -> duplicate 27.34 }
244 metric foo.two { indom -> 27.34 pmid -> 27.*.* }
245
246 INST oldid -> newid
247
248 The instance identified by the internal instance identifier ol‐
249 did is renumbered to newid. Both oldid and newid are integers
250 in the range 0 to 231-1.
251
252 As a special case, newid may be the keyword DELETE and then the
253 instance oldid will be expunged from outlog which removes it
254 from the instance domain metadata and removes all values of
255 this instance for all the associated metrics.
256
257 A metric rewriting rule has the form:
258
259 METRIC metricid { metricspec ... }
260
261 where metricid identifies one or more existing metrics from inlog using
262 either a metric name, or the internal encoding for a metric's PMID as
263 domain.cluster.item. In the latter case, typically domain would be an
264 integer in the range 1 to 510, cluster would be an integer in the range
265 0 to 4095, and item would be an integer in the range 0 to 1023.
266
267 As special cases item could be an asterisk ``*'' which means the rule
268 applies to every metric with a domain number of domain and a cluster
269 number of cluster, or cluster could be an asterisk which means the rule
270 applies to every metric with a domain number of domain and an item num‐
271 ber of item, or both cluster and item could be asterisks, and rule ap‐
272 plies to every metric with a domain number of domain.
273
274 If a designated metric is not in inlog the rule has no effect.
275
276 The metricspec is zero or more of the following clauses:
277
278
279 DELETE
280
281 The metric is completely removed from outlog, both the metadata
282 and all values in results are expunged.
283
284
285 INDOM -> newdomain.newserial [ pick ]
286
287 Modifies the metadata to change the instance domain for this
288 metric. The new instance domain must exist in outlog.
289
290 The optional pick clause may be used to select one input value,
291 or compute an aggregate value from the instances in an input
292 result, or assign an internal instance identifier to a single
293 output value. If no pick clause is specified, the default be‐
294 haviour is to copy all input values from each input result to
295 an output result, however if the input instance domain is sin‐
296 gular (indom PM_INDOM_NULL) then the one output value must be
297 assigned an internal instance identifier, which is 0 by de‐
298 fault, unless over-ridden by a INST or INAME clause as defined
299 below.
300
301 The choices for pick are as follows:
302
303 OUTPUT FIRST
304 choose the value of the first instance from each
305 input result
306
307 OUTPUT LAST choose the value of the last instance from each in‐
308 put result
309
310 OUTPUT INST instid
311 choose the value of the instance with internal in‐
312 stance identifier instid from each result; the se‐
313 quence of rewriting rules ensures the OUTPUT pro‐
314 cessing happens before instance identifier renum‐
315 bering from any associated indom rule, so instid
316 should be one of the internal instance identifiers
317 that appears in inlog
318
319 OUTPUT INAME "name"
320 choose the value of the instance with name for its
321 external instance name from each result; the se‐
322 quence of rewriting rules ensures the OUTPUT pro‐
323 cessing happens before instance renaming from any
324 associated indom rule, so name should be one of the
325 external instance names that appears in inlog
326
327 OUTPUT MIN choose the smallest value in each result (metric
328 type must be numeric and output instance will be 0
329 for a non-singular instance domain)
330
331 OUTPUT MAX choose the largest value in each result (metric
332 type must be numeric and output instance will be 0
333 for a non-singular instance domain)
334
335 OUTPUT SUM choose the sum of all values in each result (metric
336 type must be numeric and output instance will be 0
337 for a non-singular instance domain)
338
339 OUTPUT AVG choose the average of all values in each result
340 (metric type must be numeric and output instance
341 will be 0 for a non-singular instance domain)
342
343 If the input instance domain is singular (indom PM_INDOM_NULL)
344 then independent of any pick specifications, there is at most
345 one value in each input result and so FIRST, LAST, MIN, MAX,
346 SUM and AVG are all equivalent and the output instance identi‐
347 fier will be 0.
348
349 In general it is an error to specify a rewriting action for the
350 same metadata or result values more than once, e.g. more than
351 one INDOM clause for the same instance domain. The one excep‐
352 tion is the possible interaction between the INDOM clauses in
353 the indom and metric rules. For example the metric sample.bin
354 is defined over the instance domain 29.2 in inlog and the fol‐
355 lowing is acceptable (albeit redundant):
356 indom 29.* { indom -> 109.* }
357 metric sample.bin { indom -> 109.2 }
358 However the following is an error, because the instance domain
359 for sample.bin has two conflicting definitions:
360 indom 29.* { indom -> 109.* }
361 metric sample.bin { indom -> 123.2 }
362
363
364 INDOM -> NULL[ pick ]
365
366 The metric (which must have been previously defined over an in‐
367 stance domain) is being modified to be a singular metric. This
368 involves a metadata change and collapsing all results for this
369 metric so that multiple values become one value.
370
371 The optional pick part of the clause defines how the one value
372 for each result should be calculated and follows the same rules
373 as described for the non-NULL INDOM case above.
374
375 In the absence of pick, the default is OUTPUT FIRST.
376
377
378 NAME -> newname
379
380 Renames the metric in the PCP archive's metadata that supports
381 the Performance Metrics Name Space (PMNS). newname should not
382 match any existing name in the archive's PMNS and must follow
383 the syntactic rules for valid metric names as outlined in
384 PMNS(5).
385
386
387 PMID -> newdomain.newcluster.newitem
388
389 Modifies the metadata and results to renumber the metric's
390 PMID. As special cases, newcluster could be an asterisk ``*''
391 which means use cluster from the metric rewriting rule and/or
392 item could be an asterisk which means use item from the metric
393 rewriting rule. This is most useful when cluster and/or item
394 is also an asterisk. So for example:
395 metric 30.*.* { pmid -> 123.*.* }
396 will move all metrics from domain 30 to domain 123.
397
398
399 SEM -> newsem
400
401 Change the semantics of the metric. newsem should be the XXX
402 part of the name of one of the PM_SEM_XXX macros defined in
403 <pcp/pmapi.h> or pmLookupDesc(3), e.g. COUNTER for
404 PM_TYPE_COUNTER.
405
406 No data value rewriting is performed as a result of the SEM
407 clause, so the usefulness is limited to cases where a version
408 of the associated PMDA was exporting incorrect semantics for
409 the metric. pmlogreduce(1) may provide an alternative in cases
410 where re-computation of result values is desired.
411
412
413 TYPE -> newtype
414
415 Change the type of the metric which alters the metadata and may
416 change the encoding of values in results. newtype should be
417 the XXX part of the name of one of the PM_TYPE_XXX macros de‐
418 fined in <pcp/pmapi.h> or pmLookupDesc(3), e.g. FLOAT for
419 PM_TYPE_FLOAT.
420
421 Type conversion is only supported for cases where the old and
422 new metric type is numeric, so PM_TYPE_STRING, PM_TYPE_AGGRE‐
423 GATE and PM_TYPE_EVENT are not allowed. Even for the numeric
424 cases, some conversions may produce run-time errors, e.g. inte‐
425 ger overflow, or attempting to rewrite a negative value into an
426 unsigned type.
427
428
429 TYPE IF oldtype -> newtype
430
431 The same as the preceding TYPE clause, except the type of the
432 metric is only changed to newtype if the type of the metric in
433 inlog is oldtype.
434
435 This useful in cases where the type of metricid in inlog may be
436 platform dependent and so more than one type rewriting rule is
437 required.
438
439
440 UNITS -> newunits [ RESCALE ]
441
442 newunits is six values separated by commas. The first 3 values
443 describe the dimension of the metric along the dimensions of
444 space, time and count; these are integer values, usually 0, 1
445 or -1. The remaining 3 values describe the scale of the met‐
446 ric's values in the dimensions of space, time and count. Space
447 scale values should be 0 (if the space dimension is 0), else
448 the XXX part of the name of one of the PM_SPACE_XXX macros,
449 e.g. KBYTE for PM_TYPE_KBYTE. Time scale values should be 0
450 (if the time dimension is 0), else the XXX part of the name of
451 one of the PM_TIME_XXX macros, e.g. SEC for PM_TIME_SEC.
452 Count scale values should be 0 (if the time dimension is 0),
453 else ONE for PM_COUNT_ONE.
454
455 The PM_SPACE_XXX, PM_TIME_XXX and PM_COUNT_XXX macros are de‐
456 fined in <pcp/pmapi.h> or pmLookupDesc(3).
457
458 When the scale is changed (but the dimension is unaltered) the
459 optional keyword RESCALE may be used to chose value rescaling
460 as per the -s command line option, but applied to just this
461 metric.
462
463
464 When changing the domain number for a metric or instance domain,
465 the new domain number will usually match an existing PMDA's domain
466 number. If this is not the case, then the new domain number should
467 not be randomly chosen; consult $PCP_VAR_DIR/pmns/stdpmid for do‐
468 main numbers that are already assigned to PMDAs.
469
470 A text rewriting rule modifies a help text record and has the form:
471
472 TEXT textid [ texttype ] [ "textcontent" ] { textspec ... }
473
474 where textid identifies the metric or instance domain with which the
475 text is currently associated, and is either METRIC metricid or INDOM
476 domain.serial.
477
478 metricid has the same form and meaning as for a METRIC rewriting rule
479 (see above) and domain.serial has the same form and meaning as for an
480 INDOM rewriting rule (see above).
481
482 The optional texttype identifies the type of text and may be one of
483 ONELINE to select the one line help text, HELP to select the full help
484 text, or ALL or an asterisk ``*'' to select both types of help text.
485 If texttype is not specified, then the default is ONELINE.
486
487 The optional textcontent further restricts the selected text records to
488 those containing the specified content. Characters such as double
489 quotes may be escaped by preceding them with a backslash ``\''.
490
491 If a designated help text record is not in inlog the rule has no ef‐
492 fect.
493
494 The textspec is zero or more of the following clauses:
495
496 DELETE
497
498 The selected text is completely removed from outlog.
499
500 INDOM -> newdomain.newserial
501
502 Reassociates the text with the specified instance domain. As a
503 special case, newserial could be an asterisk ``*'' which means
504 use serial from the text rewriting rule, although this is most
505 useful when serial is also an asterisk. So for example:
506 text indom 29.* all { indom -> 109.* }
507 will reassociate all text associated with instance domains from
508 domain 29 to domain 109.
509
510 METRIC -> newdomain.newcluster.newitem
511
512 Reassociates the text with the specified metric. As special
513 cases, newcluster could be an asterisk ``*'' which means use
514 cluster from the text rewriting rule and/or item could be an
515 asterisk which means use item from the text rewriting rule.
516 This is most useful when cluster and/or item is also an aster‐
517 isk. So for example:
518 text metric 30.*.* all { metric -> 123.*.* }
519 will reassociate all text associated with metrics from domain
520 30 to domain 123.
521
522 TEXT -> "new-text"
523
524 Replaces the content of the selected text with new-text.
525
526 A label rewriting rule modifies a label record and has the form:
527
528 LABEL labelid [ instance ] [ "label-name" ] [ "label-value" ] { label‐
529 spec ... }
530
531 where labelid refers to the global context or identifies the metric do‐
532 main, metric cluster, metric item, instance domain, or instance domain
533 instances with which the label is currently associated, and is either
534 CONTEXT or DOMAIN domainid or CLUSTER domainid.clusterid or ITEM metri‐
535 cid or INDOM domain.serial or INSTANCES domain.serial.
536
537 metricid has the same form and meaning as for a METRIC rewriting rule
538 (see above). clusterid may be an asterisk ``*'' which means the rule
539 applies to every metric with a domain number of domainid in the same
540 way as an asterisk may be used for the cluster within metricid.
541
542 domain.serial has the same form and meaning as for an INDOM rewriting
543 rule (see above).
544
545 In the case of an INSTANCES labelid, the name or number of a specific
546 instance may be optionally specified as instance. This name or number
547 number may be omitted or specified as an asterisk ``*'' to indicate
548 that labels for all instances of the specified instance domain are se‐
549 lected. If an instance name is specified, it must be within double
550 quotes. If the instance name contains any embedded spaces then special
551 care needs to be taken in respect of the PCP instance naming rule that
552 treats the leading non-space part of the instance name as the unique
553 portion of the name for the purposes of matching and ensuring unique‐
554 ness within an instance domain, refer to pmdaInstance(3) for a discus‐
555 sion of this issue.
556
557 In all cases, a "label-name" and/or a "label-value" may be optionally
558 specified in double quotes in order to select labels with the given
559 name and/or given value. These may individually be omitted or speci‐
560 fied as asterisks ``*'' to indicate that labels with all names and/or
561 values are selected.
562
563 If a designated label record is not in inlog the rule has no effect.
564
565 The labelspec is zero or more of the following clauses:
566
567 DELETE
568
569 The selected labels are completely removed from outlog.
570
571 NEW "new-label-name" "new-label-value"
572
573 A new label with the name "new-label-name" and the value "new-
574 label-value" is created and associated with the specified la‐
575 belid and optional instance (in the case of a INSTANCES la‐
576 belid). If "label-name" or "label-value" were specified, then
577 they are ignored with a warning. If instance is not specified
578 for an INSTANCES labelid, then a new label will be created for
579 each instance in the specified instance domain.
580
581 LABEL -> "new-label-name"
582
583 The name of the selected label(s) is changed to "new-label-
584 name".
585
586 VALUE -> "new-label-value"
587
588 The value of the selected label(s) is changed to "new-label-
589 value".
590
591 DOMAIN -> newdomain
592
593 Reassociates the selected label(s) with the specified metric
594 domain. For example:
595 label domain 30 { domain -> 123 }
596 will reassociate all labels associated with domains from domain
597 30 to domain 123.
598
599 CLUSTER -> newdomain.newcluster
600
601 Reassociates the selected label(s) with the specified metric
602 cluster. As a special case, newcluster could be an asterisk
603 ``*'' which means use cluster from the label rewriting rule.
604 This is most useful when cluster is also an asterisk. So for
605 example:
606 label cluster 30.* { cluster -> 123.* }
607 will reassociate all labels associated with clusters from do‐
608 main 30 to domain 123.
609
610 ITEM -> newdomain.newcluster.newitem
611
612 Reassociates the selected label(s) with the specified metric
613 item. As special cases, newcluster could be an asterisk ``*''
614 which means use cluster from the label rewriting rule and/or
615 item could be an asterisk which means use item from the label
616 rewriting rule. This is most useful when cluster and/or item
617 is also an asterisk. So for example:
618 label item 30.*.* { item -> 123.*.* }
619 will reassociate all labels associated with metrics from domain
620 30 to domain 123.
621
622 INDOM -> newdomain.newserial
623
624 Reassociates the selected label(s) with the specified instance
625 domain. As a special case, newserial could be an asterisk
626 ``*'' which means use serial from the label rewriting rule, al‐
627 though this is most useful when serial is also an asterisk. So
628 for example:
629 label indom 29.* { indom -> 109.* }
630 will reassociate all labels associated with instance domains
631 from domain 29 to domain 109.
632
633 INSTANCES -> newdomain.newserial
634
635 This is the same as INDOM except that it reassociates the se‐
636 lected label(s) with the instances of the specified instance
637 domain.
638
640 To promote the values of the per-disk IOPS metrics to 64-bit to allow
641 aggregation over a long time period for capacity planning, or because
642 the PMDA has changed to export 64-bit counters and we want to convert
643 old archives so they can be processed alongside new archives.
644 metric disk.dev.read { type -> U64 }
645 metric disk.dev.write { type -> U64 }
646 metric disk.dev.total { type -> U64 }
647
648 The instances associated with the load average metric kernel.all.load
649 could be renamed and renumbered by the rules below.
650 # for the Linux PMDA, the kernel.all.load metric is defined
651 # over instance domain 60.2
652 indom 60.2 {
653 inst 1 -> 60 iname "1 minute" -> "60 second"
654 inst 5 -> 300 iname "5 minute" -> "300 second"
655 inst 15 -> 900 iname "15 minute" -> "900 second"
656 }
657
658 If we decide to split the ``proc'' metrics out of the Linux PMDA, this
659 will involve changing the domain number for the PMID of these metrics
660 and the associated instance domains. The rules below would rewrite an
661 old archive to match the changes after the PMDA split.
662 # all Linux proc metrics are in 7 clusters
663 metric 60.8.* { pmid -> 123.*.* }
664 metric 60.9.* { pmid -> 123.*.* }
665 metric 60.13.* { pmid -> 123.*.* }
666 metric 60.24.* { pmid -> 123.*.* }
667 metric 60.31.* { pmid -> 123.*.* }
668 metric 60.32.* { pmid -> 123.*.* }
669 metric 60.51.* { pmid -> 123.*.* }
670 # only one instance domain for Linux proc metrics
671 indom 60.9 { indom -> 123.0 }
672
673 If the metric foo.count_em was exported as a native ``long'' then it
674 could be a 32-bit integer on some platforms and a 64-bit integer on
675 other platforms. Subsequent investigations show the value is in fact
676 unsigned, so the following rules could be used.
677 metric foo.count_em {
678 type if 32 -> U32
679 type if 64 -> U64
680 }
681
683 All error conditions detected by pmlogrewrite are reported on stderr
684 with textual (if sometimes terse) explanation.
685
686 Should the input archive log be corrupted (this can happen if the pm‐
687 logger instance writing the log suddenly dies), then pmlogrewrite will
688 detect and report the position of the corruption in the file, and any
689 subsequent information from that archive log will not be processed.
690
691 If the input archive contains no archive records then an ``empty ar‐
692 chive'' warning is issued and no processing is performed.
693
694 If any error is detected, pmlogrewrite will exit with a non-zero sta‐
695 tus.
696
698 For each of the inlog and outlog archive logs, several physical files
699 are used.
700
701 archive.meta
702 metadata (metric descriptions, instance domains, etc.) for the ar‐
703 chive log
704
705 archive.0
706 initial volume of metrics values (subsequent volumes have suffixes
707 1, 2, ...).
708
709 archive.index
710 temporal index to support rapid random access to the other files
711 in the archive log.
712
714 Environment variables with the prefix PCP_ are used to parameterize the
715 file and directory names used by PCP. On each installation, the file
716 /etc/pcp.conf contains the local values for these variables. The
717 $PCP_CONF variable may be used to specify an alternative configuration
718 file, as described in pcp.conf(5).
719
720 For environment variables affecting PCP tools, see pmGetOptions(3).
721
723 PCPIntro(1), pmdumplog(1), pmlogger(1), pmlogextract(1), pmloglabel(1),
724 pmlogreduce(1), pmdaInstance(3), pmLookupDesc(3), pcp.conf(5),
725 pcp.env(5) and PMNS(5).
726
727
728
729Performance Co-Pilot PMLOGREWRITE(1)