Debian 3.9.10debian/3.9.10debian

1 files changed, 1002 insertions, 0 deletions

diff --git a/man/man1/pmlogrewrite.1 b/man/man1/pmlogrewrite.1
new file mode 100644
index 0000000..8808b42
--- /dev/null
+++ b/man/man1/pmlogrewrite.1
@@ -0,0 +1,1002 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2011 Ken McDonell.  All Rights Reserved.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 2 of the License, or (at your
+.\" option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+.\" for more details.
+.\" 
+.\"
+.TH PMLOGREWRITE 1 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmlogrewrite\f1 \- rewrite Performance Co-Pilot archives
+.SH SYNOPSIS
+\f3$PCP_BINADM_DIR/pmlogrewrite\f1
+[\f3\-Cdiqsvw \f1]
+[\f3\-c\f1 \f2config\f1]
+\f2inlog\f1 [\f2outlog\f1]
+.SH DESCRIPTION
+.de KW
+\\f(BI\\$1\\fP\\$2
+..
+.B pmlogrewrite
+reads a Performance Co-Pilot (PCP) archive log
+identified by
+.I inlog
+and creates a PCP archive log in
+.IR outlog .
+Under normal usage, the
+.B \-c
+option will be used to nominate a configuration file or files
+that contains specifications (see the
+.B "REWRITING RULES SYNTAX"
+section below)
+that describe how the data and metadata from
+.I inlog
+should be transformed to produce
+.IR outlog .
+.PP
+The typical uses for
+.B pmlogrewrite
+would be to accommodate the evolution of Performance Metric Domain Agents
+(PMDAs) where the names, metadata and semantics of metrics and their associated
+instance domains may change over time, e.g. promoting the type of a metric
+from a 32-bit to a 64-bit integer, or renaming a group of metrics.
+Refer to the
+.B EXAMPLES
+section for some additional use cases.
+.PP
+.B pmlogrewrite
+is most useful where PMDA changes, or errors in the production environment,
+result in archives that cannot be combined with
+.BR pmlogextract (1).
+By pre-processing the archives with
+.B pmlogrewrite
+the resulting archives may be able to be merged with
+.BR pmlogextract (1).
+.PP
+The input
+.I inlog
+must be a PCP archive log
+created by
+.BR pmlogger (1),
+or possibly one of the tools that read and create PCP archives, e.g.
+.BR pmlogextract (1)
+and
+.BR pmlogreduce (1).
+.PP
+If no
+.B \-c
+option is specified, then the default behavior simply creates
+.I outlog
+as a copy of
+.IR inlog .
+This is a little more complicated than
+.BR cat (1),
+as each PCP archive is made up of several physical files.
+.PP
+While
+.B pmlogrewrite
+may be used to repair some data consistency issues in PCP archives,
+there is also a class of repair tasks that cannot be handled by
+.B pmlogrewrite
+and
+.BR pmloglabel (1)
+may be a useful tool in these cases.
+.SH COMMAND LINE OPTIONS
+The command line options for
+.B pmlogrewrite
+are as follows:
+.TP 7
+.B \-C
+Parse the rewriting rules and quit.
+.I outlog
+is not created.
+When
+.B \-C
+is specified, this also sets
+.B \-v
+and
+.B \-w
+so that all warnings and verbose messages are displayed as
+.I config
+is parsed.
+.TP 7
+.BI \-c " config"
+If
+.I config
+is a file or symbolic link,
+read and parse rewriting rules from there.
+If
+.I config
+is a directory, then all of the files or symbolic links in that
+directory (excluding those beginning with a period ``.'') will
+be used to provide the rewriting rules.
+Multiple
+.B \-c
+options are allowed.
+.TP 7
+.B \-d
+Desperate mode.  Normally if a fatal error occurs, all trace of
+the partially written PCP archive
+.I outlog
+is removed.  With the
+.B \-d
+option, the partially created
+.I outlog
+archive log is not removed.
+.TP 7
+.B \-i
+Rather than creating
+.IR outlog ,
+.I inlog
+is rewritten in place when the
+.B \-i
+option is used.
+A new archive is created using temporary file names and then renamed to 
+.I inlog
+in such a way that
+if any errors (not warnings) are encountered,
+.I inlog
+remains unaltered.
+.TP 7
+.B \-q
+Quick mode, where if there are no rewriting actions to be
+performed (none of the global data, instance domains or metrics
+from
+.I inlog
+will be changed), then
+.B pmlogrewrite
+will exit (with status 0, so success) immediately after parsing
+the configuration file(s) and
+.I outlog
+is not created.
+.TP 7
+.B \-s
+When the ``units'' of a metric are changed, if the dimension in terms
+of space, time and count is unaltered, then the scaling factor is being changed,
+e.g. BYTE to KBYTE, or MSEC\u\s-3-1\s0\d to USEC\u\s-3-1\s0\d, or the
+composite MBYTE.SEC\u\s-3-1\s0\d to KBYTE.USEC\u\s-3-1\s0\d.
+The
+motivation may be (a) that the original metadata was wrong but the
+values in
+.I inlog
+are correct, or (b) the metadata is changing so the values need
+to change as well.  The default
+.B pmlogrewrite
+behaviour matches case (a).  If case (b) applies, then use the
+.B \-s
+option and the values of all the
+metrics with a scale factor change in each result will be rescaled.
+For finer control over value rescaling refer to
+the
+.KW RESCALE
+option for the
+.KW UNITS
+clause of the metric rewriting rule described below.
+.TP 7
+.BI \-v
+Increase verbosity of diagnostic output.
+.TP 7
+.BI \-w
+Emit warnings.  Normally
+.B pmlogrewrite
+remains silent for any warning that is not fatal and
+it is expected that for a particular archive, some (or indeed, all)
+of the rewriting specifications may not apply.  For example, changes to
+a PMDA may be captured in a set of rewriting rules, but a single archive
+may not contain all of the modified metrics nor all of the modified
+instance domains and/or instances.  Because these cases are expected,
+they do not prevent
+.B pmlogrewrite
+executing, and rules that do not apply to
+.I inlog
+are silently ignored by default.
+Similarly, some rewriting rules may involve no change because
+the metadata in
+.I inlog
+already matches the intent of the rewriting rule to correct data
+from a previous version of a PMDA.
+The
+.B \-w
+flag forces warnings to be emitted for all of these cases.
+.PP
+The argument
+.I outlog
+is required in all cases, except when
+.B \-i
+is specified.
+.SH REWRITING RULES SYNTAX
+A configuration file
+contains zero or more rewriting rules as defined below.
+.PP
+Keywords and special punctuation characters are shown below in
+.KW bolditalic
+font and are case-insensitive, so
+.KW METRIC ,
+.KW metric
+and
+.KW Metric
+are all equivalent in rewriting rules.
+.PP
+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.
+.PP
+A
+.B global
+rewriting rule has the form:
+.PP
+.KW GLOBAL
+.KW {
+.I globalspec
+\&...
+.KW }
+.PP
+where
+.I globalspec
+is zero or more of the following clauses:
+.RS +4n
+.PP
+.KW HOSTNAME
+.KW ->
+.I hostname
+.RS +4n
+.PP
+Modifies the label records in the
+.I outlog
+PCP archive, so that the metrics will appear to have
+been collected from the host
+.IR hostname .
+.RE
+.PP
+.KW TIME
+.KW ->
+.I delta
+.RS +4n
+.PP
+Both metric values and the instance domain metadata in a PCP
+archive carry timestamps.
+This clause forces all the timestamps to be adjusted by
+.IR delta ,
+where
+.I 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.
+.RE
+.PP
+.KW TZ
+.KW ->
+\f(BI"\fP\fItimezone\fP\f(BI"\fP
+.RS +4n
+.PP
+Modifies the label records in the
+.I outlog
+PCP archive, so that the metrics will appear to have been
+collected from a host with a local timezone of
+.IR timezone .
+.I timezone
+must be enclosed in quotes, and should conform to the valid
+timezone syntax rules for the local platform.
+.RE
+.RE
+.PP
+An
+.B indom
+rewriting rule modifies an instance domain and has the form:
+.PP
+.KW INDOM
+\fIdomain\fP\f(BI.\fP\fIserial\fP
+.KW {
+.I indomspec
+\&...
+.KW }
+.PP
+where
+.I domain
+and
+.I serial
+identify one or more existing instance domains from
+.I inlog
+\- typically
+.I domain
+would be an integer in the range 1 to 510
+and
+.I serial
+would be an integer in the range 0 to 4194304.
+.PP
+As a special
+case
+.I serial
+could be an asterisk ``*'' which means the rule applies to every
+instance domain with a domain number of
+.IR domain .
+.PP
+If a designated instance domain is not in
+.I inlog
+the rule has no effect.
+.PP
+The
+.I indomspec
+is zero or more of the following clauses:
+.RS +4n
+.PP
+.KW INAME
+"\fIoldname\fP"
+.KW ->
+"\fInewname\fP"
+.RS +4n
+.PP
+The instance identified by the external instance name
+.I oldname
+is renamed to
+.IR newname .
+Both
+.I oldname
+and
+.I newname
+must be enclosed in quotes.
+.PP
+As a special case, the new name may be the keyword
+.KW DELETE
+(with no quotes), and then the instance
+.I oldname
+will be expunged from
+.I outlog
+which removes it from the instance domain metadata and removes all
+values of this instance for all the associated metrics.
+.PP
+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
+.BR pmdaInstance (3)
+for a discussion of this issue.
+.PP
+As an illustration, consider the hypothetical instance domain for a metric
+which contains 2 instances with the following names:
+.RS +4
+.ft CW
+.nf
+red
+eek urk
+.fi
+.ft P
+.RE
+.PP
+Then some possible
+.KW INAME
+clauses might be:
+.TP +10n
+\f(CW"eek" -> "yellow like a flower"\fP
+Acceptable,
+.I oldname
+"eek" matches the "eek urk" instance.
+.TP +10n
+\f(CW"red" -> "eek"\fP
+Error,
+.I newname
+"eek" matches the existing "eek urk"
+instance.
+.TP +10n
+\f(CW"eek urk" -> "red of another hue"\fP
+Error,
+.I newname
+"red of another hue" matches the existing "red"
+instance.
+.RE
+.PP
+.KW INDOM
+.KW ->
+\fInewdomain\fP\f(BI.\fP\fInewserial\fP
+.RS +4n
+.PP
+Modifies the metadata for the instance domain and every metric associated
+with the instance domain.
+As a special case,
+.I newserial
+could be an asterisk ``*'' which means use
+.I serial
+from the 
+.B indom
+rewriting rule, although this is most useful when
+.I serial
+is also an asterisk.
+So for example:
+.RS +4n
+.ft CW
+indom 29.* { indom -> 109.* }
+.ft P
+.RE
+will move all instance domains from domain 29 to domain 109.
+.RE
+.PP
+.KW INDOM
+.KW ->
+.KW DUPLICATE
+\fInewdomain\fP\f(BI.\fP\fInewserial\fP
+.RS +4n
+.PP
+A special case of the previous
+.KW INDOM
+clause where the instance domain is a duplicate copy of the
+\fIdomain\fP\f(BI.\fP\fIserial\fP instance domain from the
+.I indom
+rewriting rule, and then any
+mapping rules are applied to the copied
+\fInewdomain\fP\f(BI.\fP\fInewserial\fP instance domain.  This is
+useful when a PMDA is split and the same instance domain needs to
+be replicated for domain \fIdomain\fP and domain \fInewdomain\fP.
+So for example if the metrics
+.I foo.one
+and
+.I foo.two
+are both defined over instance domain 12.34, and
+.I foo.two
+is moved to another PMDA using domain 27, then the
+following rewriting rules could be used:
+.RS +4n
+.ft CW
+indom 12.34 { indom -> duplicate 27.34 }
+.br
+metric foo.two { indom -> 27.34 pmid -> 27.*.*  }
+.ft P
+.RE
+.RE
+.PP
+.KW INST
+\fIoldid\fP
+.KW ->
+\fInewid\fP
+.RS +4n
+.PP
+The instance identified by the internal instance identifier
+.I oldid
+is renumbered to
+.IR newid .
+Both
+.I oldid
+and
+.I newid
+are integers in the range 0 to 2\u\s-331\s0\d-1.
+.PP
+As a special case,
+.I newid
+may be the keyword
+.KW DELETE
+and then the instance
+.I oldid
+will be expunged from
+.I outlog
+which removes it from the instance domain metadata and removes all
+values of this instance for all the associated metrics.
+.RE
+.RE
+.PP
+A
+.B metric
+rewriting rule has the form:
+.PP
+.KW METRIC
+.I metricid
+.KW {
+.I metricspec
+\&...
+.KW }
+.PP
+where
+.I metricid
+identifies one or more existing metrics from
+.I inlog
+using either a metric name, or the internal encoding for a metric's PMID as
+\fIdomain\fP\f(BI.\fP\fIcluster\fP\f(BI.\fP\fIitem\fP.
+In the latter case, typically
+.I domain
+would be an integer in the range 1 to 510,
+.I cluster
+would be an integer in the range 0 to 4095,
+and
+.I item
+would be an integer in the range 0 to 1023.
+.PP
+As special
+cases
+.I item
+could be an asterisk ``*'' which means the rule applies to every
+metric with a domain number of
+.I domain
+and a cluster number of
+.IR cluster ,
+or
+.I cluster
+could be an asterisk which means the rule applies to every
+metric with a domain number of
+.I domain
+and an item number of
+.IR item ,
+or both
+.I cluster
+and
+.I item
+could be asterisks, and rule applies to every metric with a domain
+number of
+.IR domain .
+.PP
+If a designated metric is not in
+.I inlog
+the rule has no effect.
+.PP
+The
+.I metricspec
+is zero or more of the following clauses:
+.RS +4n
+
+.PP
+.KW DELETE
+.RS +4n
+.PP
+The metric is completely removed from
+.IR outlog ,
+both the metadata and all values in results are expunged.
+.RE
+
+.PP
+.KW INDOM
+.KW ->
+\fInewdomain\fP\f(BI.\fP\fInewserial\fP [
+.I pick
+]
+.RS +4n
+.PP
+Modifies the metadata to change the instance domain for this metric.
+The new instance domain must exist in
+.IR outlog .
+.PP
+The optional
+.I 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
+.I 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
+.BR 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
+.KW INST
+or
+.KW INAME
+clause as defined below.
+.PP
+The choices for
+.I pick
+are as follows:
+.TP +12n
+\f(BIOUTPUT FIRST\fP
+choose the value of the first instance from each input result
+.TP +12n
+\f(BIOUTPUT LAST\fP
+choose the value of the last instance from each input result
+.TP +12n
+\f(BIOUTPUT INST\fP \fIinstid\fP
+choose the value of the instance with internal instance identifier
+.I instid
+from each result; the sequence of rewriting rules ensures the
+.KW OUTPUT
+processing happens before instance identifier renumbering
+from any associated
+.B indom
+rule, so
+.I instid
+should be one of the internal instance identifiers that appears in
+.I inlog
+.TP +12n
+\f(BIOUTPUT INAME\fP "\fIname\fP"
+choose the value of the instance with
+.I name
+for its external instance name
+from each result; the sequence of rewriting rules ensures the
+.KW OUTPUT 
+processing happens before instance renaming
+from any associated
+.B indom
+rule, so
+.I name
+should be one of the external instance names that appears in
+.I inlog
+.TP +12n
+\f(BIOUTPUT MIN\fP
+choose the smallest value in each result (metric type must be numeric
+and output instance will be 0 for a non-singular instance domain)
+.TP +12n
+\f(BIOUTPUT MAX\fP
+choose the largest value in each result (metric type must be numeric
+and output instance will be 0 for a non-singular instance domain)
+.TP +12n
+\f(BIOUTPUT SUM\fP
+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)
+.TP +12n
+\f(BIOUTPUT AVG\fP
+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)
+.PP
+If the input instance domain is singular
+(indom
+.BR PM_INDOM_NULL )
+then independent of any
+.I pick
+specifications, there is at most one value in each input result and
+so
+.KW FIRST ,
+.KW LAST ,
+.KW MIN ,
+.KW MAX ,
+.KW SUM
+and
+.KW AVG
+are all equivalent and the output instance identifier will be 0.
+.PP
+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
+.KW INDOM
+clause for the same instance domain.  The one exception is the possible
+interaction between the
+.KW INDOM
+clauses in the
+.B indom
+and
+.B metric
+rules.
+For example the metric
+.I sample.bin
+is defined over the instance domain 29.2 in
+.I inlog
+and the following is acceptable (albeit redundant):
+.RS +4n
+.ft CW
+.nf
+indom 29.* { indom -> 109.* }
+metric sample.bin { indom -> 109.2 }
+.fi
+.ft P
+.RE
+However the following is an error, because the instance domain for
+.I sample.bin
+has two conflicting definitions:
+.RS +4n
+.ft CW
+.nf
+indom 29.* { indom -> 109.* }
+metric sample.bin { indom -> 123.2 }
+.fi
+.ft P
+.RE
+.RE
+
+.PP
+.KW INDOM
+.KW ->
+.KW NULL [
+.I pick
+]
+.RS +4n
+.PP
+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.
+.PP
+The optional
+.I 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
+.KW INDOM
+case above.
+.PP
+In the absence of
+.IR pick ,
+the default is
+.KW "OUTPUT FIRST" .
+.RE
+
+.PP
+.KW NAME
+.KW ->
+.I newname
+.RS +4n
+.PP
+Renames the metric in the PCP archive's metadata that supports
+the Performance Metrics Name Space (PMNS).
+.I 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
+.BR pmns (5).
+.RE
+
+.PP
+.KW PMID
+.KW ->
+\fInewdomain\fP\f(BI.\fP\fInewcluster\fP\f(BI.\fP\fInewitem\fP
+.RS +4n
+.PP
+Modifies the metadata and results to renumber the metric's PMID.
+As special cases,
+.I newcluster
+could be an asterisk ``*'' which means use
+.I cluster
+from the 
+.B metric
+rewriting rule and/or
+.I item
+could be an asterisk which means use
+.I item
+from the 
+.B metric
+rewriting rule.
+This is most useful when
+.I cluster
+and/or
+.I item
+is also an asterisk.
+So for example:
+.RS +4n
+.ft CW
+metric 30.*.* { pmid -> 123.*.* }
+.ft P
+.RE
+will move all metrics from domain 30 to domain 123.
+.RE
+
+.PP
+.KW SEM
+.KW ->
+.I newsem
+.RS +4n
+.PP
+Change the semantics of the metric.
+.I newsem
+should be the XXX part of the name of one of the
+.B PM_SEM_XXX
+macros defined in <pcp/pmapi.h> or
+.BR pmLookupDesc (3),
+e.g.
+.KW COUNTER
+for
+.BR PM_TYPE_COUNTER .
+.PP
+No data value rewriting is performed as a result of the
+.KW SEM
+clause, so the usefulness
+is limited to cases where a version of the associated
+PMDA was exporting incorrect semantics for the metric.
+.BR pmlogreduce (1)
+may provide an alternative in cases where re-computation of result
+values is desired.
+.RE
+
+.PP
+.KW TYPE
+.KW ->
+.I newtype
+.RS +4n
+.PP
+Change the type of the metric which alters the metadata and may change the
+encoding of values in results.
+.I newtype
+should be the XXX part of the name of one of the
+.B PM_TYPE_XXX
+macros defined in <pcp/pmapi.h> or
+.BR pmLookupDesc (3),
+e.g.
+.KW FLOAT
+for
+.BR PM_TYPE_FLOAT .
+.PP
+Type conversion is only supported for cases where the old and new
+metric type is numeric, so
+.BR PM_TYPE_STRING ,
+.B PM_TYPE_AGGREGATE
+and
+.B 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.
+.RE
+
+.PP
+.KW UNITS
+.KW ->
+.I newunits
+[
+.KW RESCALE
+]
+.RS +4n
+.PP
+.I 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
+.B PM_SPACE_XXX
+macros, e.g.
+.KW KBYTE
+for
+.BR 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
+.B PM_TIME_XXX
+macros, e.g.
+.KW SEC
+for
+.BR PM_TIME_SEC .
+Count scale values should be 0 (if the time dimension is 0), else
+.KW ONE
+for
+.BR PM_COUNT_ONE .
+.PP
+The
+.BR PM_SPACE_XXX ,
+.B PM_TIME_XXX
+and
+.B PM_COUNT_XXX
+macros are defined in <pcp/pmapi.h> or
+.BR pmLookupDesc (3).
+.PP
+When the scale is changed (but the dimension is
+unaltered) the optional keyword
+.KW RESCALE
+may be used to chose value rescaling as per the
+.B \-s
+command line option, but applied to just this metric.
+.RE
+
+.PP
+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
+.B $PCP_VAR_DIR/pmns/stdpmid
+for domain numbers that are already assigned to PMDAs.
+.SH EXAMPLES
+.PP
+To promote the values of the per-disk IOPS metrics to 64-bit to
+allow aggregation over a long time period for capacity
+planning, or because the PMDA has changed to export 64-bit counters
+and we want to convert old archives so they can be processed
+alongside new archives.
+.RS +4
+.ft CW
+.nf
+metric disk.dev.read { type -> U64 }
+metric disk.dev.write { type -> U64 }
+metric disk.dev.total { type -> U64 }
+.fi
+.ft P
+.RE
+.PP
+The instances associated with the load average metric
+.B kernel.all.load
+could be renamed and renumbered by the
+rules below.
+.RS +4
+.ft CW
+.nf
+# for the Linux PMDA, the kernel.all.load metric is defined
+# over instance domain 60.2
+indom 60.2 {
+    inst 1 -> 60 iname "1 minute" -> "60 second"
+    inst 5 -> 300 iname "5 minute" -> "300 second"
+    inst 15 -> 900 iname "15 minute" -> "900 second"
+}
+.fi
+.ft P
+.RE
+.PP
+If we decide to split the ``proc'' metrics out of the Linux PMDA, this
+will involve changing the domain number for the PMID of these metrics
+and the associated instance domains.  The rules below would rewrite an
+old archive to match the changes after the PMDA split.
+.RS +4
+.ft CW
+.nf
+# all Linux proc metrics are in 7 clusters
+metric 60.8.* { pmid -> 123.*.* }
+metric 60.9.* { pmid -> 123.*.* }
+metric 60.13.* { pmid -> 123.*.* }
+metric 60.24.* { pmid -> 123.*.* }
+metric 60.31.* { pmid -> 123.*.* }
+metric 60.32.* { pmid -> 123.*.* }
+metric 60.51.* { pmid -> 123.*.* }
+# only one instance domain for Linux proc metrics
+indom 60.9 { indom -> 123.0 }
+.fi
+.ft P
+.RE
+.SH FILES
+.PD 0
+For each of the
+.I inlog
+and
+.I outlog
+archive logs, several physical files are used.
+.TP 10
+\f2archive\f3.meta
+metadata (metric descriptions, instance domains, etc.) for the archive log
+.TP
+\f2archive\f3.0
+initial volume of metrics values (subsequent volumes have suffixes
+.BR 1 ,
+.BR 2 ,
+\&...).
+.TP
+\f2archive\f3.index
+temporal index to support rapid random access to the other files in the
+archive log.
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmdaInstance (3),
+.BR pmdumplog (1),
+.BR pmlogger (1),
+.BR pmlogextract (1),
+.BR pmloglabel (1),
+.BR pmlogreduce (1),
+.BR pmLookupDesc (3),
+.BR pmns (5),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).
+.SH DIAGNOSTICS
+All error conditions detected by
+.B pmlogrewrite
+are reported on
+.I stderr
+with textual (if sometimes terse) explanation.
+.PP
+Should the input archive log be corrupted (this can happen
+if the
+.B pmlogger
+instance writing the log suddenly dies), then
+.B pmlogrewrite
+will detect and report the position of the corruption in the file,
+and any subsequent information from that archive log will not be processed.
+.PP
+If any error is detected,
+.B pmlogrewrite
+will exit with a non-zero status.