1PMLOGREWRITE(1) General Commands Manual PMLOGREWRITE(1)
2
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 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 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 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 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 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 -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 -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 -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 -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 -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 -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 -v, --verbose
94 Enable verbose mode.
95 -V version, --version=version
97 Specifies the version of the output PCP archive being produced.
98 Currently versions 2 and 3 of the archive format is supported.
99 The version of inlog must be at least version (so version upgrade
100 is allowed, but version downgrade is not). By default, in the ab‐
101 sence of the -V option, the version of outlog is the same as the
102 version of inlog.
103 -w, --warnings
105 Emit warnings. Normally pmlogrewrite remains silent for any warn‐
106 ing that is not fatal and it is expected that for a particular ar‐
107 chive, some (or indeed, all) of the rewriting specifications may
108 not apply. For example, changes to a PMDA may be captured in a
109 set of rewriting rules, but a single archive may not contain all
110 of the modified metrics nor all of the modified instance domains
111 and/or instances. Because these cases are expected, they do not
112 prevent pmlogrewrite executing, and rules that do not apply to in‐
113 log are silently ignored by default. Similarly, some rewriting
114 rules may involve no change because the metadata in inlog already
115 matches the intent of the rewriting rule to correct data from a
116 previous version of a PMDA. The -w flag forces warnings to be
117 emitted for all of these cases.
118 -?, --help
120 Display usage message and exit.
121 The argument outlog is required in all cases, except when -i is speci‐
123 fied.
124
126 A configuration file contains zero or more rewriting rules as defined
127 below.
128 Keywords and special punctuation characters are shown below in
130 bolditalic font and are case-insensitive, so METRIC, metric and Metric
131 are all equivalent in rewriting rules.
132 The character ``#'' introduces a comment and the remainder of the line
134 is ignored. Otherwise the input is relatively free format with op‐
135 tional white space (spaces, tabs or newlines) between lexical items in
136 the rules.
137 A global rewriting rule has the form:
139 GLOBAL { globalspec ... }
141 where globalspec is zero or more of the following clauses:
143 HOSTNAME -> hostname
145 Modifies the label records in the outlog PCP archive, so that
147 the metrics will appear to have been collected from the host
148 hostname.
149 TIME -> delta
151 Both metric values and the instance domain metadata in a PCP
153 archive carry timestamps. This clause forces all the time‐
154 stamps to be adjusted by delta, where delta is an optional sign
155 ``+'' (the default) or ``-'', an optional number of hours fol‐
156 lowed by a colon ``:'', an optional number of minutes followed
157 by a colon ``:'', a number of seconds, an optional fraction of
158 seconds following a period ``.''. The simplest example would
159 be ``30'' to increase the timestamps by 30 seconds. A more
160 complex example would be ``-23:59:59.999'' to move the time‐
161 stamps backwards by one millisecond less than one day.
162 TIMEZONE -> "timezone"
164 TZ -> "timezone"
165 Modifies the label records in the outlog PCP archive, so that
167 the metrics will appear to have been collected from a host with
168 a local timezone of timezone. timezone must be enclosed in
169 quotes, and should conform to the valid timezone syntax rules
170 for the local platform, usually a Posix TZ format, e.g.
171 AEST-10. See tzset(3) for more information.
172 TZ is an alias for TIMEZONE.
174 ZONEINFO -> "zoneinfo"
176 Modifies the label records in the outlog PCP archive, so that
178 the metrics will appear to have been collected from a host with
179 a local timezone of zoneinfo. zoneinfo must be enclosed in
180 quotes, and should conform to the valid zoneinfo timezone syn‐
181 tax rules for the local platform, usually a colon followed by a
182 pathname below /usr/share/zoneinfo, e.g. :Africa/Timbuktu. See
183 tzset(3) for more information.
184 The zoneinfo clause is only allowed if the output archive ver‐
186 sion is at least 3.
187 FEATURES -> feature-bits
189 Modifies the label records in the outlog PCP archive, so that
191 the metrics will appear to have been collected from system with
192 a pmlogger(1) that supports the ``features'' defined by the in‐
193 teger value feature-bits, which is formed by ``or''ing the de‐
194 sired feature flags as defined in LOGARCHIVE(5). Alterna‐
195 tively, feature-bits can be specified using the ``macro''
196 BITS() that takes a comma separated argument list of integers
197 (in the inclusive range 0 to 31) and sets the corresponding
198 bits. For example
199 features -> bits(31,7,1)
200 The features clause is only allowed if the output archive ver‐
202 sion is at least 3.
203 An indom rewriting rule modifies an instance domain and has the form:
205 INDOM domain.serial { indomspec ... }
207 where domain and serial identify one or more existing instance domains
209 from inlog - typically domain would be an integer in the range 1 to 510
210 and serial would be an integer in the range 0 to 4194304.
211 As a special case serial could be an asterisk ``*'' which means the
213 rule applies to every instance domain with a domain number of domain.
214 If a designated instance domain is not in inlog the rule has no effect.
216 The indomspec is zero or more of the following clauses:
218 INAME "oldname" -> "newname"
220 The instance identified by the external instance name oldname
222 is renamed to newname. Both oldname and newname must be en‐
223 closed in quotes.
224 As a special case, the new name may be the keyword DELETE (with
226 no quotes), and then the instance oldname will be expunged from
227 outlog which removes it from the instance domain metadata and
228 removes all values of this instance for all the associated met‐
229 rics.
230 If the instance names contain any embedded spaces then special
232 care needs to be taken in respect of the PCP instance naming
233 rule that treats the leading non-space part of the instance
234 name as the unique portion of the name for the purposes of
235 matching and ensuring uniqueness within an instance domain, re‐
236 fer to pmdaInstance(3) for a discussion of this issue.
237 As an illustration, consider the hypothetical instance domain
239 for a metric which contains 2 instances with the following
240 names:
241 red
242 eek urk
243 Then some possible INAME clauses might be:
245 "eek" -> "yellow like a flower"
247 Acceptable, oldname "eek" matches the "eek urk" in‐
248 stance.
249 "red" -> "eek"
251 Error, newname "eek" matches the existing "eek urk"
252 instance.
253 "eek urk" -> "red of another hue"
255 Error, newname "red of another hue" matches the ex‐
256 isting "red" instance.
257 INDOM -> newdomain.newserial
259 Modifies the metadata for the instance domain and every metric
261 associated with the instance domain. As a special case, newse‐
262 rial could be an asterisk ``*'' which means use serial from the
263 indom rewriting rule, although this is most useful when serial
264 is also an asterisk. So for example:
265 indom 29.* { indom -> 109.* }
266 will move all instance domains from domain 29 to domain 109.
267 INDOM -> DUPLICATE newdomain.newserial
269 A special case of the previous INDOM clause where the instance
271 domain is a duplicate copy of the domain.serial instance domain
272 from the indom rewriting rule, and then any mapping rules are
273 applied to the copied newdomain.newserial instance domain.
274 This is useful when a PMDA is split and the same instance do‐
275 main needs to be replicated for domain domain and domain newdo‐
276 main. So for example if the metrics foo.one and foo.two are
277 both defined over instance domain 12.34, and foo.two is moved
278 to another PMDA using domain 27, then the following rewriting
279 rules could be used:
280 indom 12.34 { indom -> duplicate 27.34 }
281 metric foo.two { indom -> 27.34 pmid -> 27.*.* }
282 INST oldid -> newid
284 The instance identified by the internal instance identifier ol‐
286 did is renumbered to newid. Both oldid and newid are integers
287 in the range 0 to 231-1.
288 As a special case, newid may be the keyword DELETE and then the
290 instance oldid will be expunged from outlog which removes it
291 from the instance domain metadata and removes all values of
292 this instance for all the associated metrics.
293 A metric rewriting rule has the form:
295 METRIC metricid { metricspec ... }
297 where metricid identifies one or more existing metrics from inlog using
299 either a metric name, or the internal encoding for a metric's PMID as
300 domain.cluster.item. In the latter case, typically domain would be an
301 integer in the range 1 to 510, cluster would be an integer in the range
302 0 to 4095, and item would be an integer in the range 0 to 1023.
303 As special cases item could be an asterisk ``*'' which means the rule
305 applies to every metric with a domain number of domain and a cluster
306 number of cluster, or cluster could be an asterisk which means the rule
307 applies to every metric with a domain number of domain and an item num‐
308 ber of item, or both cluster and item could be asterisks, and rule ap‐
309 plies to every metric with a domain number of domain.
310 If a designated metric is not in inlog the rule has no effect.
312 The metricspec is zero or more of the following clauses:
314 DELETE
317 The metric is completely removed from outlog, both the metadata
319 and all values in results are expunged.
320 INDOM -> newdomain.newserial [ pick ]
323 Modifies the metadata to change the instance domain for this
325 metric. The new instance domain must exist in outlog.
326 The optional pick clause may be used to select one input value,
328 or compute an aggregate value from the instances in an input
329 result, or assign an internal instance identifier to a single
330 output value. If no pick clause is specified, the default be‐
331 haviour is to copy all input values from each input result to
332 an output result, however if the input instance domain is sin‐
333 gular (indom PM_INDOM_NULL) then the one output value must be
334 assigned an internal instance identifier, which is 0 by de‐
335 fault, unless over-ridden by a INST or INAME clause as defined
336 below.
337 The choices for pick are as follows:
339 OUTPUT FIRST
341 choose the value of the first instance from each
342 input result
343 OUTPUT LAST choose the value of the last instance from each in‐
345 put result
346 OUTPUT INST instid
348 choose the value of the instance with internal in‐
349 stance identifier instid from each result; the se‐
350 quence of rewriting rules ensures the OUTPUT pro‐
351 cessing happens before instance identifier renum‐
352 bering from any associated indom rule, so instid
353 should be one of the internal instance identifiers
354 that appears in inlog
355 OUTPUT INAME "name"
357 choose the value of the instance with name for its
358 external instance name from each result; the se‐
359 quence of rewriting rules ensures the OUTPUT pro‐
360 cessing happens before instance renaming from any
361 associated indom rule, so name should be one of the
362 external instance names that appears in inlog
363 OUTPUT MIN choose the smallest value in each result (metric
365 type must be numeric and output instance will be 0
366 for a non-singular instance domain)
367 OUTPUT MAX choose the largest value in each result (metric
369 type must be numeric and output instance will be 0
370 for a non-singular instance domain)
371 OUTPUT SUM choose the sum of all values in each result (metric
373 type must be numeric and output instance will be 0
374 for a non-singular instance domain)
375 OUTPUT AVG choose the average of all values in each result
377 (metric type must be numeric and output instance
378 will be 0 for a non-singular instance domain)
379 If the input instance domain is singular (indom PM_INDOM_NULL)
381 then independent of any pick specifications, there is at most
382 one value in each input result and so FIRST, LAST, MIN, MAX,
383 SUM and AVG are all equivalent and the output instance identi‐
384 fier will be 0.
385 In general it is an error to specify a rewriting action for the
387 same metadata or result values more than once, e.g. more than
388 one INDOM clause for the same instance domain. The one excep‐
389 tion is the possible interaction between the INDOM clauses in
390 the indom and metric rules. For example the metric sample.bin
391 is defined over the instance domain 29.2 in inlog and the fol‐
392 lowing is acceptable (albeit redundant):
393 indom 29.* { indom -> 109.* }
394 metric sample.bin { indom -> 109.2 }
395 However the following is an error, because the instance domain
396 for sample.bin has two conflicting definitions:
397 indom 29.* { indom -> 109.* }
398 metric sample.bin { indom -> 123.2 }
399 INDOM -> NULL[ pick ]
402 The metric (which must have been previously defined over an in‐
404 stance domain) is being modified to be a singular metric. This
405 involves a metadata change and collapsing all results for this
406 metric so that multiple values become one value.
407 The optional pick part of the clause defines how the one value
409 for each result should be calculated and follows the same rules
410 as described for the non-NULL INDOM case above.
411 In the absence of pick, the default is OUTPUT FIRST.
413 NAME -> newname
416 Renames the metric in the PCP archive's metadata that supports
418 the Performance Metrics Name Space (PMNS). newname should not
419 match any existing name in the archive's PMNS and must follow
420 the syntactic rules for valid metric names as outlined in
421 PMNS(5).
422 PMID -> newdomain.newcluster.newitem
425 Modifies the metadata and results to renumber the metric's
427 PMID. As special cases, newcluster could be an asterisk ``*''
428 which means use cluster from the metric rewriting rule and/or
429 item could be an asterisk which means use item from the metric
430 rewriting rule. This is most useful when cluster and/or item
431 is also an asterisk. So for example:
432 metric 30.*.* { pmid -> 123.*.* }
433 will move all metrics from domain 30 to domain 123.
434 SEM -> newsem
437 Change the semantics of the metric. newsem should be the XXX
439 part of the name of one of the PM_SEM_XXX macros defined in
440 <pcp/pmapi.h> or pmLookupDesc(3), e.g. COUNTER for
441 PM_TYPE_COUNTER.
442 No data value rewriting is performed as a result of the SEM
444 clause, so the usefulness is limited to cases where a version
445 of the associated PMDA was exporting incorrect semantics for
446 the metric. pmlogreduce(1) may provide an alternative in cases
447 where re-computation of result values is desired.
448 TYPE -> newtype
451 Change the type of the metric which alters the metadata and may
453 change the encoding of values in results. newtype should be
454 the XXX part of the name of one of the PM_TYPE_XXX macros de‐
455 fined in <pcp/pmapi.h> or pmLookupDesc(3), e.g. FLOAT for
456 PM_TYPE_FLOAT.
457 Type conversion is only supported for cases where the old and
459 new metric type is numeric, so PM_TYPE_STRING, PM_TYPE_AGGRE‐
460 GATE and PM_TYPE_EVENT are not allowed. Even for the numeric
461 cases, some conversions may produce run-time errors, e.g. inte‐
462 ger overflow, or attempting to rewrite a negative value into an
463 unsigned type.
464 TYPE IF oldtype -> newtype
467 The same as the preceding TYPE clause, except the type of the
469 metric is only changed to newtype if the type of the metric in
470 inlog is oldtype.
471 This useful in cases where the type of metricid in inlog may be
473 platform dependent and so more than one type rewriting rule is
474 required.
475 UNITS -> newunits [ RESCALE ]
478 newunits is six values separated by commas. The first 3 values
480 describe the dimension of the metric along the dimensions of
481 space, time and count; these are integer values, usually 0, 1
482 or -1. The remaining 3 values describe the scale of the met‐
483 ric's values in the dimensions of space, time and count. Space
484 scale values should be 0 (if the space dimension is 0), else
485 the XXX part of the name of one of the PM_SPACE_XXX macros,
486 e.g. KBYTE for PM_TYPE_KBYTE. Time scale values should be 0
487 (if the time dimension is 0), else the XXX part of the name of
488 one of the PM_TIME_XXX macros, e.g. SEC for PM_TIME_SEC.
489 Count scale values should be 0 (if the time dimension is 0),
490 else ONE for PM_COUNT_ONE.
491 The PM_SPACE_XXX, PM_TIME_XXX and PM_COUNT_XXX macros are de‐
493 fined in <pcp/pmapi.h> or pmLookupDesc(3).
494 When the scale is changed (but the dimension is unaltered) the
496 optional keyword RESCALE may be used to chose value rescaling
497 as per the -s command line option, but applied to just this
498 metric.
499 When changing the domain number for a metric or instance domain,
502 the new domain number will usually match an existing PMDA's domain
503 number. If this is not the case, then the new domain number should
504 not be randomly chosen; consult $PCP_VAR_DIR/pmns/stdpmid for do‐
505 main numbers that are already assigned to PMDAs.
506 A text rewriting rule modifies a help text record and has the form:
508 TEXT textid [ texttype ] [ "textcontent" ] { textspec ... }
510 where textid identifies the metric or instance domain with which the
512 text is currently associated, and is either METRIC metricid or INDOM
513 domain.serial.
514 metricid has the same form and meaning as for a METRIC rewriting rule
516 (see above) and domain.serial has the same form and meaning as for an
517 INDOM rewriting rule (see above).
518 The optional texttype identifies the type of text and may be one of
520 ONELINE to select the one line help text, HELP to select the full help
521 text, or ALL or an asterisk ``*'' to select both types of help text.
522 If texttype is not specified, then the default is ONELINE.
523 The optional textcontent further restricts the selected text records to
525 those containing the specified content. Characters such as double
526 quotes may be escaped by preceding them with a backslash ``\''.
527 If a designated help text record is not in inlog the rule has no ef‐
529 fect.
530 The textspec is zero or more of the following clauses:
532 DELETE
534 The selected text is completely removed from outlog.
536 INDOM -> newdomain.newserial
538 Reassociates the text with the specified instance domain. As a
540 special case, newserial could be an asterisk ``*'' which means
541 use serial from the text rewriting rule, although this is most
542 useful when serial is also an asterisk. So for example:
543 text indom 29.* all { indom -> 109.* }
544 will reassociate all text associated with instance domains from
545 domain 29 to domain 109.
546 METRIC -> newdomain.newcluster.newitem
548 Reassociates the text with the specified metric. As special
550 cases, newcluster could be an asterisk ``*'' which means use
551 cluster from the text rewriting rule and/or item could be an
552 asterisk which means use item from the text rewriting rule.
553 This is most useful when cluster and/or item is also an aster‐
554 isk. So for example:
555 text metric 30.*.* all { metric -> 123.*.* }
556 will reassociate all text associated with metrics from domain
557 30 to domain 123.
558 TEXT -> "new-text"
560 Replaces the content of the selected text with new-text.
562 A label rewriting rule modifies a label record and has the form:
564 LABEL labelid [ instance ] [ "label-name" ] [ "label-value" ] { label‐
566 spec ... }
567 where labelid refers to the global context or identifies the metric do‐
569 main, metric cluster, metric item, instance domain, or instance domain
570 instances with which the label is currently associated, and is either
571 CONTEXT or DOMAIN domainid or CLUSTER domainid.clusterid or ITEM metri‐
572 cid or INDOM domain.serial or INSTANCES domain.serial.
573 metricid has the same form and meaning as for a METRIC rewriting rule
575 (see above). clusterid may be an asterisk ``*'' which means the rule
576 applies to every metric with a domain number of domainid in the same
577 way as an asterisk may be used for the cluster within metricid.
578 domain.serial has the same form and meaning as for an INDOM rewriting
580 rule (see above).
581 In the case of an INSTANCES labelid, the name or number of a specific
583 instance may be optionally specified as instance. This name or number
584 number may be omitted or specified as an asterisk ``*'' to indicate
585 that labels for all instances of the specified instance domain are se‐
586 lected. If an instance name is specified, it must be within double
587 quotes. If the instance name contains any embedded spaces then special
588 care needs to be taken in respect of the PCP instance naming rule that
589 treats the leading non-space part of the instance name as the unique
590 portion of the name for the purposes of matching and ensuring unique‐
591 ness within an instance domain, refer to pmdaInstance(3) for a discus‐
592 sion of this issue.
593 In all cases, a "label-name" and/or a "label-value" may be optionally
595 specified in double quotes in order to select labels with the given
596 name and/or given value. These may individually be omitted or speci‐
597 fied as asterisks ``*'' to indicate that labels with all names and/or
598 values are selected.
599 If a designated label record is not in inlog the rule has no effect.
601 The labelspec is zero or more of the following clauses:
603 DELETE
605 The selected labels are completely removed from outlog.
607 NEW "new-label-name" "new-label-value"
609 A new label with the name "new-label-name" and the value "new-
611 label-value" is created and associated with the specified la‐
612 belid and optional instance (in the case of a INSTANCES la‐
613 belid). If "label-name" or "label-value" were specified, then
614 they are ignored with a warning. If instance is not specified
615 for an INSTANCES labelid, then a new label will be created for
616 each instance in the specified instance domain.
617 LABEL -> "new-label-name"
619 The name of the selected label(s) is changed to "new-label-
621 name".
622 VALUE -> "new-label-value"
624 The value of the selected label(s) is changed to "new-label-
626 value".
627 DOMAIN -> newdomain
629 Reassociates the selected label(s) with the specified metric
631 domain. For example:
632 label domain 30 { domain -> 123 }
633 will reassociate all labels associated with domains from domain
634 30 to domain 123.
635 CLUSTER -> newdomain.newcluster
637 Reassociates the selected label(s) with the specified metric
639 cluster. As a special case, newcluster could be an asterisk
640 ``*'' which means use cluster from the label rewriting rule.
641 This is most useful when cluster is also an asterisk. So for
642 example:
643 label cluster 30.* { cluster -> 123.* }
644 will reassociate all labels associated with clusters from do‐
645 main 30 to domain 123.
646 ITEM -> newdomain.newcluster.newitem
648 Reassociates the selected label(s) with the specified metric
650 item. As special cases, newcluster could be an asterisk ``*''
651 which means use cluster from the label rewriting rule and/or
652 item could be an asterisk which means use item from the label
653 rewriting rule. This is most useful when cluster and/or item
654 is also an asterisk. So for example:
655 label item 30.*.* { item -> 123.*.* }
656 will reassociate all labels associated with metrics from domain
657 30 to domain 123.
658 INDOM -> newdomain.newserial
660 Reassociates the selected label(s) with the specified instance
662 domain. As a special case, newserial could be an asterisk
663 ``*'' which means use serial from the label rewriting rule, al‐
664 though this is most useful when serial is also an asterisk. So
665 for example:
666 label indom 29.* { indom -> 109.* }
667 will reassociate all labels associated with instance domains
668 from domain 29 to domain 109.
669 INSTANCES -> newdomain.newserial
671 This is the same as INDOM except that it reassociates the se‐
673 lected label(s) with the instances of the specified instance
674 domain.
675
677 To promote the values of the per-disk IOPS metrics to 64-bit to allow
678 aggregation over a long time period for capacity planning, or because
679 the PMDA has changed to export 64-bit counters and we want to convert
680 old archives so they can be processed alongside new archives.
681 metric disk.dev.read { type -> U64 }
682 metric disk.dev.write { type -> U64 }
683 metric disk.dev.total { type -> U64 }
684 The instances associated with the load average metric kernel.all.load
686 could be renamed and renumbered by the rules below.
687 # for the Linux PMDA, the kernel.all.load metric is defined
688 # over instance domain 60.2
689 indom 60.2 {
690 inst 1 -> 60 iname "1 minute" -> "60 second"
691 inst 5 -> 300 iname "5 minute" -> "300 second"
692 inst 15 -> 900 iname "15 minute" -> "900 second"
693 }
694 If we decide to split the ``proc'' metrics out of the Linux PMDA, this
696 will involve changing the domain number for the PMID of these metrics
697 and the associated instance domains. The rules below would rewrite an
698 old archive to match the changes after the PMDA split.
699 # all Linux proc metrics are in 7 clusters
700 metric 60.8.* { pmid -> 123.*.* }
701 metric 60.9.* { pmid -> 123.*.* }
702 metric 60.13.* { pmid -> 123.*.* }
703 metric 60.24.* { pmid -> 123.*.* }
704 metric 60.31.* { pmid -> 123.*.* }
705 metric 60.32.* { pmid -> 123.*.* }
706 metric 60.51.* { pmid -> 123.*.* }
707 # only one instance domain for Linux proc metrics
708 indom 60.9 { indom -> 123.0 }
709 If the metric foo.count_em was exported as a native ``long'' then it
711 could be a 32-bit integer on some platforms and a 64-bit integer on
712 other platforms. Subsequent investigations show the value is in fact
713 unsigned, so the following rules could be used.
714 metric foo.count_em {
715 type if 32 -> U32
716 type if 64 -> U64
717 }
718
720 All error conditions detected by pmlogrewrite are reported on stderr
721 with textual (if sometimes terse) explanation.
722 Should the input archive log be corrupted (this can happen if the pm‐
724 logger instance writing the log suddenly dies), then pmlogrewrite will
725 detect and report the position of the corruption in the file, and any
726 subsequent information from that archive log will not be processed.
727 If the input archive contains no archive records then an ``empty ar‐
729 chive'' warning is issued and no processing is performed.
730 If any error is detected, pmlogrewrite will exit with a non-zero sta‐
732 tus.
733
735 For each of the inlog and outlog archive logs, several physical files
736 are used.
737 archive.meta
739 metadata (metric descriptions, instance domains, etc.) for the ar‐
740 chive log
741 archive.0
743 initial volume of metrics values (subsequent volumes have suffixes
744 1, 2, ...).
745 archive.index
747 temporal index to support rapid random access to the other files
748 in the archive log.
749
751 Environment variables with the prefix PCP_ are used to parameterize the
752 file and directory names used by PCP. On each installation, the file
753 /etc/pcp.conf contains the local values for these variables. The
754 $PCP_CONF variable may be used to specify an alternative configuration
755 file, as described in pcp.conf(5).
756 For environment variables affecting PCP tools, see pmGetOptions(3).
758
760 PCPIntro(1), pmdumplog(1), pmlogextract(1), pmlogger(1), pmloglabel(1),
761 pmlogreduce(1), PMAPI(3), pmdaInstance(3), pmLookupDesc(3), tzset(3),
762 LOGARCHIVE(5), pcp.conf(5), pcp.env(5) and PMNS(5).
763Performance Co-Pilot PMLOGREWRITE(1)