Modifies the label records in the outlog PCP archive, so that the metrics will appear to have been collected from the host hostname.

Both metric values and the instance domain metadata in a PCP archive carry timestamps. This clause forces all the timestamps to be adjusted by delta, where delta is an optional sign ``+'' (the default) or ``-'', an optional number of hours followed by a colon ``:'', an optional number of minutes followed by a colon ``:'', a number of seconds, an optional fraction of seconds following a period ``.''. The simplest example would be ``30'' to increase the timestamps by 30 seconds. A more complex example would be ``-23:59:59.999'' to move the timestamps backwards by one millisecond less than one day.

Modifies the label records in the outlog PCP archive, so that the metrics will appear to have been collected from a host with a local timezone of timezone. timezone must be enclosed in double quotes, and should conform to the valid timezone syntax rules for the local platform, usually a Posix TZ format, e.g. AEST-10. See tzset(3) for more information.

TZ is an alias for TIMEZONE.

Modifies the label records in the outlog PCP archive, so that the metrics will appear to have been collected from a host with a local timezone of zoneinfo. zoneinfo must be enclosed in double quotes, and should conform to the valid zoneinfo timezone syntax rules for the local platform, usually a colon followed by a pathname below /usr/share/zoneinfo, e.g. :Africa/Timbuktu. See tzset(3) for more information.

The zoneinfo clause is only allowed if the output archive version is at least 3.

Modifies the label records in the outlog PCP archive, so that the metrics will appear to have been collected from system with a pmlogger(1) that supports the ``features'' defined by the integer value feature-bits, which is formed by ``or''ing the desired feature flags as defined in LOGARCHIVE(5). Alternatively, feature-bits can be specified using the ``macro'' BITS() that takes a comma separated argument list of integers (in the inclusive range 0 to 31) and sets the corresponding bits. For example

The features clause is only allowed if the output archive version is at least 3.

The instance identified by the external instance name oldname is renamed to newname. Both oldname and newname must be enclosed in double quotes.

As a special case, the new name may be the keyword DELETE (with no double quotes), and then the instance oldname will be expunged from outlog which removes it from the instance domain metadata and removes all values of this instance for all the associated metrics.

If the instance names contain any embedded spaces then special care needs to be taken in respect of the PCP instance naming rule that treats the leading non-space part of the instance name as the unique portion of the name for the purposes of matching and ensuring uniqueness within an instance domain, refer to pmdaInstance(3) for a discussion of this issue.

As an illustration, consider the hypothetical instance domain for a metric which contains 2 instances with the following names:

red
eek urk

Then some possible INAME clauses might be:

"eek" -> "yellow like a flower"

Acceptable, oldname "eek" matches the "eek urk" instance.

"red" -> "eek"

Error, newname "eek" matches the existing "eek urk" instance.

"eek urk" -> "red of another hue"

Error, newname "red of another hue" matches the existing "red" instance.

Every external instance name in the instance domain is matched against the regular expression pattern and when a match is found, the name is changed based on the parts of the name matched by pattern and the replacement recipe. pattern follows the syntax of a Posix Extended Regular Expression (see regex(7)) and replacement follows the syntax of the s command of sed(1), so & and \1 through \9 may be used to select all or substrings of the instance name that matches pattern.

Note that the match-and-replace is done at most once per external instance name, so if there are repeated sequences of the name that match pattern only the first one will be matched and replacement applied.

pattern is normally enclosed in slashes (/) or double quotes ("). An escape (\) may be used before any of the metacharacters described in regex(3) to specify a literal character, e.g. \( or \[ or \+ ... The enclosing delimiters cannot be escaped, so to embed a literal slash, use double quotes as the delimiter, or vice versa.

replacement is normally enclosed by double quotes (") or slashes (/). An escape (\) may be used before & or \ to specify these characters literally. The enclosing delimiters cannot be escaped, so to embed a double quote, use slashes as the delimiter, or vice versa.

If the instance names after replacement contain any embedded spaces then special care needs to be taken in respect of the PCP instance naming rule that treats the leading non-space part of the instance name as the unique portion of the name for the purposes of matching and ensuring uniqueness within an instance domain. Refer to pmdaInstance(3) for a discussion of this issue.

Here are some examples:

{ iname replace /[a-z]*foo[a-z]*/ -> "FOO" }

replace any word containing "foo" with "FOO"

{ iname replace "([0-9]+) /.*/(.*)" -> "\1 \2" }

removes a directory path, so the instance name (for one of the proc PMDA's metrics) "2981799 /home/kenj/bin/foobar" would become "2981799 foobar", hiding the user's home directory and implicitly the user's login name

Replace every external instance name in the instance domain by the string "inst [redacted]" where inst is the internal instance identifier in ASCII format.

Modifies the metadata for the instance domain and every metric associated with the instance domain. As a special case, newserial could be an asterisk ``*'' which means use serial from the indom rewriting rule, although this is most useful when serial is also an asterisk. So for example:

A special case of the previous INDOM clause where the instance domain is a duplicate copy of the domain.serial instance domain from the indom rewriting rule, and then any mapping rules are applied to the copied newdomain.newserial instance domain. This is useful when a PMDA is split and the same instance domain needs to be replicated for domain domain and domain newdomain. So for example if the metrics foo.one and foo.two are both defined over instance domain 12.34, and foo.two is moved to another PMDA using domain 27, then the following rewriting rules could be used:

The instance identified by the internal instance identifier oldid is renumbered to newid. Both oldid and newid are integers in the range 0 to 231-1.

As a special case, newid may be the keyword DELETE and then the instance oldid will be expunged from outlog which removes it from the instance domain metadata and removes all values of this instance for all the associated metrics.

The metric is completely removed from outlog, both the metadata and all values in results are expunged.

Modifies the metadata to change the instance domain for this metric. The new instance domain must exist in outlog.

The optional pick clause may be used to select one input value, or compute an aggregate value from the instances in an input result, or assign an internal instance identifier to a single output value. If no pick clause is specified, the default behaviour is to copy all input values from each input result to an output result, however if the input instance domain is singular (indom PM_INDOM_NULL) then the one output value must be assigned an internal instance identifier, which is 0 by default, unless over-ridden by a INST or INAME clause as defined below.

The choices for pick are as follows:

OUTPUT FIRST

choose the value of the first instance from each input result

OUTPUT LAST

choose the value of the last instance from each input result

OUTPUT INST instid

choose the value of the instance with internal instance identifier instid from each result; the sequence of rewriting rules ensures the OUTPUT processing happens before instance identifier renumbering from any associated indom rule, so instid should be one of the internal instance identifiers that appears in inlog

OUTPUT INAME "name"

choose the value of the instance with name for its external instance name from each result; the sequence of rewriting rules ensures the OUTPUT processing happens before instance renaming from any associated indom rule, so name should be one of the external instance names that appears in inlog

OUTPUT MIN

choose the smallest value in each result (metric type must be numeric and output instance will be 0 for a non-singular instance domain)

OUTPUT MAX

choose the largest value in each result (metric type must be numeric and output instance will be 0 for a non-singular instance domain)

OUTPUT SUM

choose the sum of all values in each result (metric type must be numeric and output instance will be 0 for a non-singular instance domain)

OUTPUT AVG

choose the average of all values in each result (metric type must be numeric and output instance will be 0 for a non-singular instance domain)

If the input instance domain is singular (indom PM_INDOM_NULL) then independent of any pick specifications, there is at most one value in each input result and so FIRST, LAST, MIN, MAX, SUM and AVG are all equivalent and the output instance identifier will be 0.

In general it is an error to specify a rewriting action for the same metadata or result values more than once, e.g. more than one INDOM clause for the same instance domain. The one exception is the possible interaction between the INDOM clauses in the indom and metric rules. For example the metric sample.bin is defined over the instance domain 29.2 in inlog and the following is acceptable (albeit redundant):

indom 29.* { indom -> 109.* }
metric sample.bin { indom -> 109.2 }

indom 29.* { indom -> 109.* }
metric sample.bin { indom -> 123.2 }

The metric (which must have been previously defined over an instance domain) is being modified to be a singular metric. This involves a metadata change and collapsing all results for this metric so that multiple values become one value.

The optional pick part of the clause defines how the one value for each result should be calculated and follows the same rules as described for the non-NULL INDOM case above.

In the absence of pick, the default is OUTPUT FIRST.

Renames the metric in the PCP archive's metadata that supports the Performance Metrics Name Space (PMNS). newname should not match any existing name in the archive's PMNS and must follow the syntactic rules for valid metric names as outlined in PMNS(5).

Modifies the metadata and results to renumber the metric's PMID. As special cases, newcluster could be an asterisk ``*'' which means use cluster from the metric rewriting rule and/or item could be an asterisk which means use item from the metric rewriting rule. This is most useful when cluster and/or item is also an asterisk. So for example:

Change the semantics of the metric. newsem should be the XXX part of the name of one of the PM_SEM_XXX macros defined in <pcp/pmapi.h> or pmLookupDesc(3), e.g. COUNTER for PM_TYPE_COUNTER.

No data value rewriting is performed as a result of the SEM clause, so the usefulness is limited to cases where a version of the associated PMDA was exporting incorrect semantics for the metric. pmlogreduce(1) may provide an alternative in cases where re-computation of result values is desired.

Change the type of the metric which alters the metadata and may change the encoding of values in results. newtype should be the XXX part of the name of one of the PM_TYPE_XXX macros defined in <pcp/pmapi.h> or pmLookupDesc(3), e.g. FLOAT for PM_TYPE_FLOAT.

Type conversion is only supported for cases where the old and new metric type is numeric, so PM_TYPE_STRING, PM_TYPE_AGGREGATE and PM_TYPE_EVENT are not allowed. Even for the numeric cases, some conversions may produce run-time errors, e.g. integer overflow, or attempting to rewrite a negative value into an unsigned type.

The same as the preceding TYPE clause, except the type of the metric is only changed to newtype if the type of the metric in inlog is oldtype.

This useful in cases where the type of metricid in inlog may be platform dependent and so more than one type rewriting rule is required.

newunits is six values separated by commas. The first 3 values describe the dimension of the metric along the dimensions of space, time and count; these are integer values, usually 0, 1 or -1. The remaining 3 values describe the scale of the metric's values in the dimensions of space, time and count. Space scale values should be 0 (if the space dimension is 0), else the XXX part of the name of one of the PM_SPACE_XXX macros, e.g. KBYTE for PM_TYPE_KBYTE. Time scale values should be 0 (if the time dimension is 0), else the XXX part of the name of one of the PM_TIME_XXX macros, e.g. SEC for PM_TIME_SEC. Count scale values should be 0 (if the time dimension is 0), else ONE for PM_COUNT_ONE.

The PM_SPACE_XXX, PM_TIME_XXX and PM_COUNT_XXX macros are defined in <pcp/pmapi.h> or pmLookupDesc(3).

When the scale is changed (but the dimension is unaltered) the optional keyword RESCALE may be used to chose value rescaling as per the -s command line option, but applied to just this metric.

The value for every instance of the metric is matched against the regular expression pattern and when a match is found, the value is changed based on the parts of the value matched by pattern and the replacement recipe. pattern follows the syntax of a Posix Extended Regular Expression (see regex(7)) and replacement follows the syntax of the s command of sed(1), so & and \1 through \9 may be used to select all or substrings of the value that matches pattern.

Note that the match-and-replace is done at most once per metric value, so if there are repeated sequences of the metric value that match pattern only the first one will be matched and replacement applied.

pattern is normally enclosed in slashes (/) or double quotes ("). An escape (\) may be used before any of the metacharacters described in regex(3) to specify a literal character, e.g. \( or \[ or \+ ... The enclosing delimiters cannot be escaped, so to embed a literal slash, use double quotes as the delimiter, or vice versa.

replacement is normally enclosed by double quotes (") or slashes (/). An escape (\) may be used before & or \ to specify these characters literally. The enclosing delimiters cannot be escaped, so to embed a double quote, use slashes as the delimiter, or vice versa.

The REPLACE keyword is optional.

This clause can only be applied to metrics with values of type PM_TYPE_STRING.

Here are some examples:

{ value /.*/ -> "" }

remove the value everywhere

value "/.*/(.*)" -> "\1" }

removes a directory path, so the metric value "mumble /home/kenj/bin/foobar fumble" would become "mumble foobar fumble", hiding the user's home directory and implicitly the user's login name

The selected text is completely removed from outlog.

Reassociates the text with the specified instance domain. As a special case, newserial could be an asterisk ``*'' which means use serial from the text rewriting rule, although this is most useful when serial is also an asterisk. So for example:

Reassociates the text with the specified metric. As special cases, newcluster could be an asterisk ``*'' which means use cluster from the text rewriting rule and/or item could be an asterisk which means use item from the text rewriting rule. This is most useful when cluster and/or item is also an asterisk. So for example:

Replaces the content of the selected text with new-text.

The selected labels are completely removed from outlog.

A new label with the name "new-label-name" and the value "new-label-value" is created and associated with the specified labelid and optional instance (in the case of a INSTANCES labelid). If "label-name" or "label-value" were specified, then they are ignored with a warning. If instance is not specified for an INSTANCES labelid, then a new label will be created for each instance in the specified instance domain.

The name of the selected label(s) is changed to "new-label-name".

The value of the selected label(s) is changed to "new-label-value".

Reassociates the selected label(s) with the specified metric domain. For example:

Reassociates the selected label(s) with the specified metric cluster. As a special case, newcluster could be an asterisk ``*'' which means use cluster from the label rewriting rule. This is most useful when cluster is also an asterisk. So for example:

Reassociates the selected label(s) with the specified metric item. As special cases, newcluster could be an asterisk ``*'' which means use cluster from the label rewriting rule and/or item could be an asterisk which means use item from the label rewriting rule. This is most useful when cluster and/or item is also an asterisk. So for example:

Reassociates the selected label(s) with the specified instance domain. As a special case, newserial could be an asterisk ``*'' which means use serial from the label rewriting rule, although this is most useful when serial is also an asterisk. So for example:

This is the same as INDOM except that it reassociates the selected label(s) with the instances of the specified instance domain.