1PMLOGREWRITE(1)             General Commands Manual            PMLOGREWRITE(1)
2
3
4

NAME

6       pmlogrewrite - rewrite Performance Co-Pilot archives
7

SYNOPSIS

9       $PCP_BINADM_DIR/pmlogrewrite [-Cdiqsvw?]  [-c config] inlog [outlog]
10

DESCRIPTION

12       pmlogrewrite  reads  a  set  of Performance Co-Pilot (PCP) archive logs
13       identified by inlog and creates a PCP archive  log  in  outlog.   Under
14       normal  usage,  the  -c option will be used to nominate a configuration
15       file or files that contains specifications  (see  the  REWRITING  RULES
16       SYNTAX  section  below)  that  describe  how the data and metadata from
17       inlog should be transformed to produce outlog.
18
19       The typical uses for pmlogrewrite would be to accommodate the evolution
20       of  Performance  Metric Domain Agents (PMDAs) where the names, metadata
21       and semantics of metrics and  their  associated  instance  domains  may
22       change  over time, e.g. promoting the type of a metric from a 32-bit to
23       a 64-bit integer, or renaming a group of metrics.  Refer to  the  EXAM‐
24       PLES section for some additional use cases.
25
26       pmlogrewrite  is  most useful where PMDA changes, or errors in the pro‐
27       duction environment, result in archives that cannot  be  combined  with
28       pmlogextract(1).   By pre-processing the archives with pmlogrewrite the
29       resulting archives may be able to be merged with pmlogextract(1).
30
31       The input inlog must be a set of PCP archive  logs  created  by  pmlog‐
32       ger(1), or possibly one of the tools that read and create PCP archives,
33       e.g.  pmlogextract(1) and pmlogreduce(1).  inlog is  a  comma-separated
34       list  of names, each of which may be the base name of an archive or the
35       name of a directory containing one or more archives.
36
37       If no -c option is specified, then the default behavior simply  creates
38       outlog  as  a  copy  of  inlog.  This is a little more complicated than
39       cat(1), as each PCP archive is made up of several physical files.
40
41       While pmlogrewrite may be used to repair some data  consistency  issues
42       in  PCP  archives, there is also a class of repair tasks that cannot be
43       handled by pmlogrewrite and pmloglabel(1) may be a useful tool in these
44       cases.
45

OPTIONS

47       The available command line options are:
48
49       -c config, --config=config
50            If  config  is  a  file or symbolic link, read and parse rewriting
51            rules from there.  If config is a directory, then all of the files
52            or  symbolic  links  in  that directory (excluding those beginning
53            with a period ``.'') will be used to provide the rewriting  rules.
54            Multiple -c options are allowed.
55
56       -C, --check
57            Parse  the rewriting rules and quit.  outlog is not created.  When
58            -C is specified, this also sets -v and -w so that all warnings and
59            verbose messages are displayed as config is parsed.
60
61       -d, --desperate
62            Desperate  mode.   Normally  if a fatal error occurs, all trace of
63            the partially written PCP archive outlog is removed.  With the  -d
64            option, the partially created outlog archive log is not removed.
65
66       -i   Rather  than creating outlog, inlog is rewritten in place when the
67            -i option is used.  A new archive is created using temporary  file
68            names  and  then renamed to inlog in such a way that if any errors
69            (not warnings) are encountered, inlog remains unaltered.
70
71       -q, --quick
72            Quick mode, where if there are no rewriting  actions  to  be  per‐
73            formed  (none of the global data, instance domains or metrics from
74            inlog will be changed), then pmlogrewrite will exit  (with  status
75            0, so success) immediately after parsing the configuration file(s)
76            and outlog is not created.
77
78       -s, --scale
79            When the ``units'' of a metric are changed, if  the  dimension  in
80            terms of space, time and count is unaltered, then the scaling fac‐
81            tor is being changed, e.g. BYTE to KBYTE, or MSEC-1 to USEC-1,  or
82            the  composite MBYTE.SEC-1 to KBYTE.USEC-1.  The motivation may be
83            (a) that the original metadata was wrong but the values  in  inlog
84            are correct, or (b) the metadata is changing so the values need to
85            change as well.  The default pmlogrewrite behaviour  matches  case
86            (a).   If  case (b) applies, then use the -s option and the values
87            of all the metrics with a scale factor change in each result  will
88            be  rescaled.  For finer control over value rescaling refer to the
89            RESCALE option for the UNITS clause of the metric  rewriting  rule
90            described below.
91
92       -v, --verbose
93            Enable verbose mode.
94
95       -w, --warning
96            Emit warnings.  Normally pmlogrewrite remains silent for any warn‐
97            ing that is not fatal and it is expected that for a particular ar‐
98            chive,  some  (or indeed, all) of the rewriting specifications may
99            not apply.  For example, changes to a PMDA may be  captured  in  a
100            set  of  rewriting rules, but a single archive may not contain all
101            of the modified metrics nor all of the modified  instance  domains
102            and/or  instances.   Because these cases are expected, they do not
103            prevent pmlogrewrite executing, and rules that  do  not  apply  to
104            inlog  are silently ignored by default.  Similarly, some rewriting
105            rules may involve no change because the metadata in inlog  already
106            matches  the  intent  of the rewriting rule to correct data from a
107            previous version of a PMDA.  The -w flag  forces  warnings  to  be
108            emitted for all of these cases.
109
110       -?   Display usage message and exit.
111
112       The  argument outlog is required in all cases, except when -i is speci‐
113       fied.
114

REWRITING RULES SYNTAX

116       A configuration file contains zero or more rewriting rules  as  defined
117       below.
118
119       Keywords   and  special  punctuation  characters  are  shown  below  in
120       bolditalic font and are case-insensitive, so METRIC, metric and  Metric
121       are all equivalent in rewriting rules.
122
123       The  character ``#'' introduces a comment and the remainder of the line
124       is ignored.   Otherwise  the  input  is  relatively  free  format  with
125       optional  white  space (spaces, tabs or newlines) between lexical items
126       in the rules.
127
128       A global rewriting rule has the form:
129
130       GLOBAL { globalspec ...  }
131
132       where globalspec is zero or more of the following clauses:
133
134           HOSTNAME -> hostname
135
136               Modifies the label records in the outlog PCP archive,  so  that
137               the  metrics  will  appear to have been collected from the host
138               hostname.
139
140           TIME -> delta
141
142               Both metric values and the instance domain metadata  in  a  PCP
143               archive  carry  timestamps.   This  clause forces all the time‐
144               stamps to be adjusted by delta, where delta is an optional sign
145               ``+''  (the default) or ``-'', an optional number of hours fol‐
146               lowed by a colon ``:'', an optional number of minutes  followed
147               by  a colon ``:'', a number of seconds, an optional fraction of
148               seconds following a period ``.''.  The simplest  example  would
149               be  ``30''  to  increase  the timestamps by 30 seconds.  A more
150               complex example would be ``-23:59:59.999'' to  move  the  time‐
151               stamps backwards by one millisecond less than one day.
152
153           TZ -> "timezone"
154
155               Modifies  the  label records in the outlog PCP archive, so that
156               the metrics will appear to have been collected from a host with
157               a  local  timezone  of  timezone.  timezone must be enclosed in
158               quotes, and should conform to the valid timezone  syntax  rules
159               for the local platform.
160
161       An indom rewriting rule modifies an instance domain and has the form:
162
163       INDOM domain.serial { indomspec ...  }
164
165       where  domain and serial identify one or more existing instance domains
166       from inlog - typically domain would be an integer in the range 1 to 510
167       and serial would be an integer in the range 0 to 4194304.
168
169       As  a  special  case  serial could be an asterisk ``*'' which means the
170       rule applies to every instance domain with a domain number of domain.
171
172       If a designated instance domain is not in inlog the rule has no effect.
173
174       The indomspec is zero or more of the following clauses:
175
176           INAME "oldname" -> "newname"
177
178               The instance identified by the external instance  name  oldname
179               is  renamed  to  newname.   Both  oldname  and  newname must be
180               enclosed in quotes.
181
182               As a special case, the new name may be the keyword DELETE (with
183               no quotes), and then the instance oldname will be expunged from
184               outlog which removes it from the instance domain  metadata  and
185               removes all values of this instance for all the associated met‐
186               rics.
187
188               If the instance names contain any embedded spaces then  special
189               care  needs  to  be taken in respect of the PCP instance naming
190               rule that treats the leading non-space  part  of  the  instance
191               name  as  the  unique  portion  of the name for the purposes of
192               matching and ensuring uniqueness  within  an  instance  domain,
193               refer to pmdaInstance(3) for a discussion of this issue.
194
195               As  an  illustration, consider the hypothetical instance domain
196               for a metric which contains  2  instances  with  the  following
197               names:
198                   red
199                   eek urk
200
201               Then some possible INAME clauses might be:
202
203               "eek" -> "yellow like a flower"
204                         Acceptable,  oldname  "eek"  matches  the  "eek  urk"
205                         instance.
206
207               "red" -> "eek"
208                         Error, newname "eek" matches the existing  "eek  urk"
209                         instance.
210
211               "eek urk" -> "red of another hue"
212                         Error,  newname  "red  of  another  hue"  matches the
213                         existing "red" instance.
214
215           INDOM -> newdomain.newserial
216
217               Modifies the metadata for the instance domain and every  metric
218               associated with the instance domain.  As a special case, newse‐
219               rial could be an asterisk ``*'' which means use serial from the
220               indom  rewriting rule, although this is most useful when serial
221               is also an asterisk.  So for example:
222                   indom 29.* { indom -> 109.* }
223               will move all instance domains from domain 29 to domain 109.
224
225           INDOM -> DUPLICATE newdomain.newserial
226
227               A special case of the previous INDOM clause where the  instance
228               domain is a duplicate copy of the domain.serial instance domain
229               from the indom rewriting rule, and then any mapping  rules  are
230               applied  to  the  copied  newdomain.newserial  instance domain.
231               This is useful when a PMDA  is  split  and  the  same  instance
232               domain needs to be replicated for domain domain and domain new‐
233               domain.  So for example if the metrics foo.one and foo.two  are
234               both  defined  over instance domain 12.34, and foo.two is moved
235               to another PMDA using domain 27, then the  following  rewriting
236               rules could be used:
237                   indom 12.34 { indom -> duplicate 27.34 }
238                   metric foo.two { indom -> 27.34 pmid -> 27.*.*  }
239
240           INST oldid -> newid
241
242               The  instance  identified  by  the internal instance identifier
243               oldid is renumbered to newid.  Both oldid and newid  are  inte‐
244               gers in the range 0 to 231-1.
245
246               As a special case, newid may be the keyword DELETE and then the
247               instance oldid will be expunged from outlog  which  removes  it
248               from  the  instance  domain  metadata and removes all values of
249               this instance for all the associated metrics.
250
251       A metric rewriting rule has the form:
252
253       METRIC metricid { metricspec ...  }
254
255       where metricid identifies one or more existing metrics from inlog using
256       either  a  metric name, or the internal encoding for a metric's PMID as
257       domain.cluster.item.  In the latter case, typically domain would be  an
258       integer in the range 1 to 510, cluster would be an integer in the range
259       0 to 4095, and item would be an integer in the range 0 to 1023.
260
261       As special cases item could be an asterisk ``*'' which means  the  rule
262       applies  to  every  metric with a domain number of domain and a cluster
263       number of cluster, or cluster could be an asterisk which means the rule
264       applies to every metric with a domain number of domain and an item num‐
265       ber of item, or both cluster and item  could  be  asterisks,  and  rule
266       applies to every metric with a domain number of domain.
267
268       If a designated metric is not in inlog the rule has no effect.
269
270       The metricspec is zero or more of the following clauses:
271
272
273           DELETE
274
275               The metric is completely removed from outlog, both the metadata
276               and all values in results are expunged.
277
278
279           INDOM -> newdomain.newserial [ pick ]
280
281               Modifies the metadata to change the instance  domain  for  this
282               metric.  The new instance domain must exist in outlog.
283
284               The optional pick clause may be used to select one input value,
285               or compute an aggregate value from the instances  in  an  input
286               result,  or  assign an internal instance identifier to a single
287               output value.  If no pick clause is specified, the default  be‐
288               haviour  is  to copy all input values from each input result to
289               an output result, however if the input instance domain is  sin‐
290               gular  (indom  PM_INDOM_NULL) then the one output value must be
291               assigned  an  internal  instance  identifier,  which  is  0  by
292               default,  unless  over-ridden  by  a  INST  or  INAME clause as
293               defined below.
294
295               The choices for pick are as follows:
296
297               OUTPUT FIRST
298                           choose the value of the first  instance  from  each
299                           input result
300
301               OUTPUT LAST choose  the  value  of  the last instance from each
302                           input result
303
304               OUTPUT INST instid
305                           choose the value  of  the  instance  with  internal
306                           instance  identifier  instid  from each result; the
307                           sequence of rewriting rules ensures the OUTPUT pro‐
308                           cessing  happens  before instance identifier renum‐
309                           bering from any associated indom  rule,  so  instid
310                           should  be one of the internal instance identifiers
311                           that appears in inlog
312
313               OUTPUT INAME "name"
314                           choose the value of the instance with name for  its
315                           external   instance  name  from  each  result;  the
316                           sequence of rewriting rules ensures the OUTPUT pro‐
317                           cessing  happens  before instance renaming from any
318                           associated indom rule, so name should be one of the
319                           external instance names that appears in inlog
320
321               OUTPUT MIN  choose  the  smallest  value in each result (metric
322                           type must be numeric and output instance will be  0
323                           for a non-singular instance domain)
324
325               OUTPUT MAX  choose  the  largest  value  in each result (metric
326                           type must be numeric and output instance will be  0
327                           for a non-singular instance domain)
328
329               OUTPUT SUM  choose the sum of all values in each result (metric
330                           type must be numeric and output instance will be  0
331                           for a non-singular instance domain)
332
333               OUTPUT AVG  choose  the  average  of  all values in each result
334                           (metric type must be numeric  and  output  instance
335                           will be 0 for a non-singular instance domain)
336
337               If  the input instance domain is singular (indom PM_INDOM_NULL)
338               then independent of any pick specifications, there is  at  most
339               one  value  in  each input result and so FIRST, LAST, MIN, MAX,
340               SUM and AVG are all equivalent and the output instance  identi‐
341               fier will be 0.
342
343               In general it is an error to specify a rewriting action for the
344               same metadata or result values more than once, e.g.  more  than
345               one  INDOM clause for the same instance domain.  The one excep‐
346               tion is the possible interaction between the INDOM  clauses  in
347               the  indom and metric rules.  For example the metric sample.bin
348               is defined over the instance domain 29.2 in inlog and the  fol‐
349               lowing is acceptable (albeit redundant):
350                   indom 29.* { indom -> 109.* }
351                   metric sample.bin { indom -> 109.2 }
352               However  the following is an error, because the instance domain
353               for sample.bin has two conflicting definitions:
354                   indom 29.* { indom -> 109.* }
355                   metric sample.bin { indom -> 123.2 }
356
357
358           INDOM -> NULL[ pick ]
359
360               The metric (which must have been  previously  defined  over  an
361               instance  domain)  is  being  modified to be a singular metric.
362               This involves a metadata change and collapsing all results  for
363               this metric so that multiple values become one value.
364
365               The  optional pick part of the clause defines how the one value
366               for each result should be calculated and follows the same rules
367               as described for the non-NULL INDOM case above.
368
369               In the absence of pick, the default is OUTPUT FIRST.
370
371
372           NAME -> newname
373
374               Renames  the metric in the PCP archive's metadata that supports
375               the Performance Metrics Name Space (PMNS).  newname should  not
376               match  any  existing name in the archive's PMNS and must follow
377               the syntactic rules for  valid  metric  names  as  outlined  in
378               PMNS(5).
379
380
381           PMID -> newdomain.newcluster.newitem
382
383               Modifies  the  metadata  and  results  to renumber the metric's
384               PMID.  As special cases, newcluster could be an asterisk  ``*''
385               which  means  use cluster from the metric rewriting rule and/or
386               item could be an asterisk which means use item from the  metric
387               rewriting  rule.   This is most useful when cluster and/or item
388               is also an asterisk.  So for example:
389                   metric 30.*.* { pmid -> 123.*.* }
390               will move all metrics from domain 30 to domain 123.
391
392
393           SEM -> newsem
394
395               Change the semantics of the metric.  newsem should be  the  XXX
396               part  of  the  name  of one of the PM_SEM_XXX macros defined in
397               <pcp/pmapi.h>   or   pmLookupDesc(3),   e.g.     COUNTER    for
398               PM_TYPE_COUNTER.
399
400               No  data  value  rewriting  is performed as a result of the SEM
401               clause, so the usefulness is limited to cases where  a  version
402               of  the  associated  PMDA was exporting incorrect semantics for
403               the metric.  pmlogreduce(1) may provide an alternative in cases
404               where re-computation of result values is desired.
405
406
407           TYPE -> newtype
408
409               Change the type of the metric which alters the metadata and may
410               change the encoding of values in results.   newtype  should  be
411               the  XXX  part  of  the  name  of one of the PM_TYPE_XXX macros
412               defined in <pcp/pmapi.h> or pmLookupDesc(3),  e.g.   FLOAT  for
413               PM_TYPE_FLOAT.
414
415               Type  conversion  is only supported for cases where the old and
416               new metric type is numeric, so  PM_TYPE_STRING,  PM_TYPE_AGGRE‐
417               GATE  and  PM_TYPE_EVENT are not allowed.  Even for the numeric
418               cases, some conversions may produce run-time errors, e.g. inte‐
419               ger overflow, or attempting to rewrite a negative value into an
420               unsigned type.
421
422
423           TYPE IF oldtype -> newtype
424
425               The same as the preceding TYPE clause, except the type  of  the
426               metric  is only changed to newtype if the type of the metric in
427               inlog is oldtype.
428
429               This useful in cases where the type of metricid in inlog may be
430               platform  dependent and so more than one type rewriting rule is
431               required.
432
433
434           UNITS -> newunits [ RESCALE ]
435
436               newunits is six values separated by commas.  The first 3 values
437               describe  the  dimension  of the metric along the dimensions of
438               space, time and count; these are integer values, usually  0,  1
439               or  -1.   The remaining 3 values describe the scale of the met‐
440               ric's values in the dimensions of space, time and count.  Space
441               scale  values  should  be 0 (if the space dimension is 0), else
442               the XXX part of the name of one  of  the  PM_SPACE_XXX  macros,
443               e.g.   KBYTE  for PM_TYPE_KBYTE.  Time scale values should be 0
444               (if the time dimension is 0), else the XXX part of the name  of
445               one  of  the  PM_TIME_XXX  macros,  e.g.   SEC for PM_TIME_SEC.
446               Count scale values should be 0 (if the time  dimension  is  0),
447               else ONE for PM_COUNT_ONE.
448
449               The  PM_SPACE_XXX,  PM_TIME_XXX  and  PM_COUNT_XXX  macros  are
450               defined in <pcp/pmapi.h> or pmLookupDesc(3).
451
452               When the scale is changed (but the dimension is unaltered)  the
453               optional  keyword  RESCALE may be used to chose value rescaling
454               as per the -s command line option, but  applied  to  just  this
455               metric.
456
457
458           When  changing  the  domain number for a metric or instance domain,
459           the new domain number will usually match an existing PMDA's  domain
460           number.  If this is not the case, then the new domain number should
461           not  be  randomly  chosen;  consult  $PCP_VAR_DIR/pmns/stdpmid  for
462           domain numbers that are already assigned to PMDAs.
463
464       A text rewriting rule modifies a help text record and has the form:
465
466       TEXT textid [ texttype ] [ "textcontent" ] { textspec ...  }
467
468       where  textid  identifies  the metric or instance domain with which the
469       text is currently associated, and is either METRIC  metricid  or  INDOM
470       domain.serial.
471
472       metricid  has  the same form and meaning as for a METRIC rewriting rule
473       (see above) and domain.serial has the same form and meaning as  for  an
474       INDOM rewriting rule (see above).
475
476       The  optional  texttype  identifies  the type of text and may be one of
477       ONELINE to select the one line help text, HELP to select the full  help
478       text,  or  ALL  or an asterisk ``*'' to select both types of help text.
479       If texttype is not specified, then the default is ONELINE.
480
481       The optional textcontent further restricts the selected text records to
482       those  containing  the  specified  content.   Characters such as double
483       quotes may be escaped by preceding them with a backslash ``\''.
484
485       If a designated help text record is  not  in  inlog  the  rule  has  no
486       effect.
487
488       The textspec is zero or more of the following clauses:
489
490           DELETE
491
492               The selected text is completely removed from outlog.
493
494           INDOM -> newdomain.newserial
495
496               Reassociates the text with the specified instance domain.  As a
497               special case, newserial could be an asterisk ``*'' which  means
498               use  serial from the text rewriting rule, although this is most
499               useful when serial is also an asterisk.  So for example:
500                   text indom 29.* all { indom -> 109.* }
501               will reassociate all text associated with instance domains from
502               domain 29 to domain 109.
503
504           METRIC -> newdomain.newcluster.newitem
505
506               Reassociates  the  text  with the specified metric.  As special
507               cases, newcluster could be an asterisk ``*''  which  means  use
508               cluster  from  the  text rewriting rule and/or item could be an
509               asterisk which means use item from  the  text  rewriting  rule.
510               This  is most useful when cluster and/or item is also an aster‐
511               isk.  So for example:
512                   text metric 30.*.* all { metric -> 123.*.* }
513               will reassociate all text associated with metrics  from  domain
514               30 to domain 123.
515
516           TEXT -> "new-text"
517
518               Replaces the content of the selected text with new-text.
519
520       A label rewriting rule modifies a label record and has the form:
521
522       LABEL  labelid [ instance ] [ "label-name" ] [ "label-value" ] { label‐
523       spec ...  }
524
525       where labelid refers to the global context  or  identifies  the  metric
526       domain,  metric  cluster,  metric  item,  instance  domain, or instance
527       domain instances with which the label is currently associated,  and  is
528       either CONTEXT or DOMAIN domainid or CLUSTER domainid.clusterid or ITEM
529       metricid or INDOM domain.serial or INSTANCES domain.serial.
530
531       metricid has the same form and meaning as for a METRIC  rewriting  rule
532       (see  above).   clusterid may be an asterisk ``*'' which means the rule
533       applies to every metric with a domain number of domainid  in  the  same
534       way as an asterisk may be used for the cluster within metricid.
535
536       domain.serial  has  the same form and meaning as for an INDOM rewriting
537       rule (see above).
538
539       In the case of an INSTANCES labelid, the name or number of  a  specific
540       instance  may be optionally specified as instance.  This name or number
541       number may be omitted or specified as an  asterisk  ``*''  to  indicate
542       that  labels  for  all  instances  of the specified instance domain are
543       selected.  If an instance name is specified, it must be  within  double
544       quotes.  If the instance name contains any embedded spaces then special
545       care needs to be taken in respect of the PCP instance naming rule  that
546       treats  the  leading  non-space part of the instance name as the unique
547       portion of the name for the purposes of matching and  ensuring  unique‐
548       ness  within an instance domain, refer to pmdaInstance(3) for a discus‐
549       sion of this issue.
550
551       In all cases, a "label-name" and/or a "label-value" may  be  optionally
552       specified  in  double  quotes  in order to select labels with the given
553       name and/or given value.  These may individually be omitted  or  speci‐
554       fied  as  asterisks ``*'' to indicate that labels with all names and/or
555       values are selected.
556
557       If a designated label record is not in inlog the rule has no effect.
558
559       The labelspec is zero or more of the following clauses:
560
561           DELETE
562
563               The selected labels are completely removed from outlog.
564
565           NEW "new-label-name" "new-label-value"
566
567               A new label with the name "new-label-name" and the value  "new-
568               label-value"  is  created  and  associated  with  the specified
569               labelid and optional instance  (in  the  case  of  a  INSTANCES
570               labelid).   If  "label-name"  or  "label-value" were specified,
571               then they are ignored with a warning.  If instance is not spec‐
572               ified  for  an INSTANCES labelid, then a new label will be cre‐
573               ated for each instance in the specified instance domain.
574
575           LABEL -> "new-label-name"
576
577               The name of the selected label(s)  is  changed  to  "new-label-
578               name".
579
580           VALUE -> "new-label-value"
581
582               The  value  of  the selected label(s) is changed to "new-label-
583               value".
584
585           DOMAIN -> newdomain
586
587               Reassociates the selected label(s) with  the  specified  metric
588               domain.  For example:
589                   label domain 30 { domain -> 123 }
590               will reassociate all labels associated with domains from domain
591               30 to domain 123.
592
593           CLUSTER -> newdomain.newcluster
594
595               Reassociates the selected label(s) with  the  specified  metric
596               cluster.   As  a  special case, newcluster could be an asterisk
597               ``*'' which means use cluster from the  label  rewriting  rule.
598               This  is  most useful when cluster is also an asterisk.  So for
599               example:
600                   label cluster 30.* { cluster -> 123.* }
601               will reassociate  all  labels  associated  with  clusters  from
602               domain 30 to domain 123.
603
604           ITEM -> newdomain.newcluster.newitem
605
606               Reassociates  the  selected  label(s) with the specified metric
607               item.  As special cases, newcluster could be an asterisk  ``*''
608               which  means  use  cluster from the label rewriting rule and/or
609               item could be an asterisk which means use item from  the  label
610               rewriting  rule.   This is most useful when cluster and/or item
611               is also an asterisk.  So for example:
612                   label item 30.*.* { item -> 123.*.* }
613               will reassociate all labels associated with metrics from domain
614               30 to domain 123.
615
616           INDOM -> newdomain.newserial
617
618               Reassociates  the selected label(s) with the specified instance
619               domain.  As a special case,  newserial  could  be  an  asterisk
620               ``*''  which  means  use  serial from the label rewriting rule,
621               although this is most useful when serial is also  an  asterisk.
622               So for example:
623                   label indom 29.* { indom -> 109.* }
624               will  reassociate  all  labels associated with instance domains
625               from domain 29 to domain 109.
626
627           INSTANCES -> newdomain.newserial
628
629               This is the same as  INDOM  except  that  it  reassociates  the
630               selected  label(s) with the instances of the specified instance
631               domain.
632

EXAMPLES

634       To promote the values of the per-disk IOPS metrics to 64-bit  to  allow
635       aggregation  over  a long time period for capacity planning, or because
636       the PMDA has changed to export 64-bit counters and we want  to  convert
637       old archives so they can be processed alongside new archives.
638           metric disk.dev.read { type -> U64 }
639           metric disk.dev.write { type -> U64 }
640           metric disk.dev.total { type -> U64 }
641
642       The  instances  associated with the load average metric kernel.all.load
643       could be renamed and renumbered by the rules below.
644           # for the Linux PMDA, the kernel.all.load metric is defined
645           # over instance domain 60.2
646           indom 60.2 {
647               inst 1 -> 60 iname "1 minute" -> "60 second"
648               inst 5 -> 300 iname "5 minute" -> "300 second"
649               inst 15 -> 900 iname "15 minute" -> "900 second"
650           }
651
652       If we decide to split the ``proc'' metrics out of the Linux PMDA,  this
653       will  involve  changing the domain number for the PMID of these metrics
654       and the associated instance domains.  The rules below would rewrite  an
655       old archive to match the changes after the PMDA split.
656           # all Linux proc metrics are in 7 clusters
657           metric 60.8.* { pmid -> 123.*.* }
658           metric 60.9.* { pmid -> 123.*.* }
659           metric 60.13.* { pmid -> 123.*.* }
660           metric 60.24.* { pmid -> 123.*.* }
661           metric 60.31.* { pmid -> 123.*.* }
662           metric 60.32.* { pmid -> 123.*.* }
663           metric 60.51.* { pmid -> 123.*.* }
664           # only one instance domain for Linux proc metrics
665           indom 60.9 { indom -> 123.0 }
666
667       If  the  metric  foo.count_em was exported as a native ``long'' then it
668       could be a 32-bit integer on some platforms and  a  64-bit  integer  on
669       other  platforms.   Subsequent investigations show the value is in fact
670       unsigned, so the following rules could be used.
671           metric foo.count_em {
672                type if 32 -> U32
673                type if 64 -> U64
674           }
675

DIAGNOSTICS

677       All error conditions detected by pmlogrewrite are  reported  on  stderr
678       with textual (if sometimes terse) explanation.
679
680       Should  the  input  archive  log  be  corrupted (this can happen if the
681       pmlogger instance writing the log  suddenly  dies),  then  pmlogrewrite
682       will  detect and report the position of the corruption in the file, and
683       any subsequent information from that archive log will not be processed.
684
685       If any error is detected, pmlogrewrite will exit with a  non-zero  sta‐
686       tus.
687

FILES

689       For  each  of the inlog and outlog archive logs, several physical files
690       are used.
691
692       archive.meta
693            metadata (metric descriptions, instance domains, etc.) for the ar‐
694            chive log
695
696       archive.0
697            initial volume of metrics values (subsequent volumes have suffixes
698            1, 2, ...).
699
700       archive.index
701            temporal index to support rapid random access to the  other  files
702            in the archive log.
703

PCP ENVIRONMENT

705       Environment variables with the prefix PCP_ are used to parameterize the
706       file and directory names used by PCP.  On each installation,  the  file
707       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
708       $PCP_CONF variable may be used to specify an alternative  configuration
709       file, as described in pcp.conf(5).
710
711       For environment variables affecting PCP tools, see pmGetOptions(3).
712

SEE ALSO

714       PCPIntro(1), pmdumplog(1), pmlogger(1), pmlogextract(1), pmloglabel(1),
715       pmlogreduce(1),    pmdaInstance(3),    pmLookupDesc(3),    pcp.conf(5),
716       pcp.env(5) and PMNS(5).
717
718
719
720Performance Co-Pilot                                           PMLOGREWRITE(1)
Impressum