A configuration file contains zero or more rewriting rules as
defined below.
Keywords and special punctuation characters are shown below in
bolditalic font and are case-insensitive, so METRIC, metric and
Metric are all equivalent in rewriting rules.
The character ``#'' introduces a comment and the remainder of the
line is ignored. Otherwise the input is relatively free format
with optional white space (spaces, tabs or newlines) between
lexical items in the rules.
A global rewriting rule has the form:
GLOBAL { globalspec ... }
where globalspec is zero or more of the following clauses:
HOSTNAME -> hostname
Modifies the label records in the outlog PCP archive, so
that the metrics will appear to have been collected from
the host hostname.
TIME -> delta
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.
TZ -> "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 timezone. timezone must
be enclosed in quotes, and should conform to the valid
timezone syntax rules for the local platform.
An indom rewriting rule modifies an instance domain and has the
form:
INDOM domain.serial { indomspec ... }
where domain and serial identify one or more existing instance
domains from inlog - typically domain would be an integer in the
range 1 to 510 and serial would be an integer in the range 0 to
4194304.
As a special case serial could be an asterisk ``*'' which means
the rule applies to every instance domain with a domain number of
domain.
If a designated instance domain is not in inlog the rule has no
effect.
The indomspec is zero or more of the following clauses:
INAME "oldname" -> "newname"
The instance identified by the external instance name
oldname is renamed to newname. Both oldname and newname
must be enclosed in quotes.
As a special case, the new name may be the keyword DELETE
(with no 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.
INDOM -> newdomain.newserial
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:
indom 29.* { indom -> 109.* }
will move all instance domains from domain 29 to domain
109.
INDOM -> DUPLICATE newdomain.newserial
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:
indom 12.34 { indom -> duplicate 27.34 }
metric foo.two { indom -> 27.34 pmid -> 27.*.* }
INST oldid -> newid
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.
A metric rewriting rule has the form:
METRIC metricid { metricspec ... }
where metricid identifies one or more existing metrics from inlog
using either a metric name, or the internal encoding for a
metric's PMID as domain.cluster.item. In the latter case,
typically domain would be an integer in the range 1 to 510,
cluster would be an integer in the range 0 to 4095, and item
would be an integer in the range 0 to 1023.
As special cases item could be an asterisk ``*'' which means the
rule applies to every metric with a domain number of domain and a
cluster number of cluster, or cluster could be an asterisk which
means the rule applies to every metric with a domain number of
domain and an item number of item, or both cluster and item could
be asterisks, and rule applies to every metric with a domain
number of domain.
If a designated metric is not in inlog the rule has no effect.
The metricspec is zero or more of the following clauses:
DELETE
The metric is completely removed from outlog, both the
metadata and all values in results are expunged.
INDOM -> newdomain.newserial [ pick ]
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 }
However the following is an error, because the instance
domain for sample.bin has two conflicting definitions:
indom 29.* { indom -> 109.* }
metric sample.bin { indom -> 123.2 }
INDOM -> NULL[ pick ]
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.
NAME -> newname
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).
PMID -> newdomain.newcluster.newitem
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:
metric 30.*.* { pmid -> 123.*.* }
will move all metrics from domain 30 to domain 123.
SEM -> newsem
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.
TYPE -> newtype
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.
TYPE IF oldtype -> newtype
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.
UNITS -> newunits [ RESCALE ]
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.
When changing the domain number for a metric or instance
domain, the new domain number will usually match an existing
PMDA's domain number. If this is not the case, then the new
domain number should not be randomly chosen; consult
$PCP_VAR_DIR/pmns/stdpmid for domain numbers that are already
assigned to PMDAs.
A text rewriting rule modifies a help text record and has the
form:
TEXT textid [ texttype ] [ "textcontent" ] { textspec ... }
where textid identifies the metric or instance domain with which
the text is currently associated, and is either METRIC metricid
or INDOM domain.serial.
metricid has the same form and meaning as for a METRIC rewriting
rule (see above) and domain.serial has the same form and meaning
as for an INDOM rewriting rule (see above).
The optional texttype identifies the type of text and may be one
of ONELINE to select the one line help text, HELP to select the
full help text, or ALL or an asterisk ``*'' to select both types
of help text. If texttype is not specified, then the default is
ONELINE.
The optional textcontent further restricts the selected text
records to those containing the specified content. Characters
such as double quotes may be escaped by preceding them with a
backslash ``\''.
If a designated help text record is not in inlog the rule has no
effect.
The textspec is zero or more of the following clauses:
DELETE
The selected text is completely removed from outlog.
INDOM -> newdomain.newserial
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:
text indom 29.* all { indom -> 109.* }
will reassociate all text associated with instance
domains from domain 29 to domain 109.
METRIC -> newdomain.newcluster.newitem
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:
text metric 30.*.* all { metric -> 123.*.* }
will reassociate all text associated with metrics from
domain 30 to domain 123.
TEXT -> "new-text"
Replaces the content of the selected text with new-text.
A label rewriting rule modifies a label record and has the form:
LABEL labelid [ instance ] [ "label-name[1m"[24m [22m] [ "label-value[1m"[24m [22m] {
labelspec ... }
where labelid refers to the global context or identifies the
metric domain, metric cluster, metric item, instance domain, or
instance domain instances with which the label is currently
associated, and is either CONTEXT or DOMAIN domainid or CLUSTER
domainid.clusterid or ITEM metricid or INDOM domain.serial or
INSTANCES domain.serial.
metricid has the same form and meaning as for a METRIC rewriting
rule (see above). clusterid may be an asterisk ``*'' which means
the rule applies to every metric with a domain number of domainid
in the same way as an asterisk may be used for the cluster within
metricid.
domain.serial has the same form and meaning as for an INDOM
rewriting rule (see above).
In the case of an INSTANCES labelid, the name or number of a
specific instance may be optionally specified as instance. This
name or number number may be omitted or specified as an asterisk
``*'' to indicate that labels for all instances of the specified
instance domain are selected. If an instance name is specified,
it must be within double quotes. If the instance name contains
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.
In all cases, a "label-name[1m"[24m [22mand/or a "label-value[1m"[24m [22mmay be
optionally specified in double quotes in order to select labels
with the given name and/or given value. These may individually
be omitted or specified as asterisks ``*'' to indicate that
labels with all names and/or values are selected.
If a designated label record is not in inlog the rule has no
effect.
The labelspec is zero or more of the following clauses:
DELETE
The selected labels are completely removed from outlog.
NEW "new-label-name" "new-label-value"
A new label with the name "new-label-name[1m"[24m [22mand the value
"new-label-value[1m"[24m [22mis created and associated with the
specified labelid and optional instance (in the case of a
INSTANCES labelid). If "label-name[1m"[24m [22mor "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.
LABEL -> "new-label-name"
The name of the selected label(s) is changed to "new-
label-name[1m"[24m[22m.
VALUE -> "new-label-value"
The value of the selected label(s) is changed to "new-
label-value[1m"[24m[22m.
DOMAIN -> newdomain
Reassociates the selected label(s) with the specified
metric domain. For example:
label domain 30 { domain -> 123 }
will reassociate all labels associated with domains from
domain 30 to domain 123.
CLUSTER -> newdomain.newcluster
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:
label cluster 30.* { cluster -> 123.* }
will reassociate all labels associated with clusters from
domain 30 to domain 123.
ITEM -> newdomain.newcluster.newitem
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:
label item 30.*.* { item -> 123.*.* }
will reassociate all labels associated with metrics from
domain 30 to domain 123.
INDOM -> newdomain.newserial
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:
label indom 29.* { indom -> 109.* }
will reassociate all labels associated with instance
domains from domain 29 to domain 109.
INSTANCES -> newdomain.newserial
This is the same as INDOM except that it reassociates the
selected label(s) with the instances of the specified
instance domain.
