|
NAME | SYNOPSIS | DESCRIPTION | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON |
PMDIFF(1) General Commands Manual PMDIFF(1)
pmdiff - compares archives and report significant differences
pmdiff [-d/--keep] [-z/--hostzone] [-p/--precision precision]
[-q/--threshold thres] [-S/--start starttime] [-T/--finish endtime]
[-B/--begin starttime] [-E/--end endtime] [-x metric] [-X file]
[--skip-excluded] [--skip-missing] [-Z/--timezone timezone] archive1
[archive2]
pmdiff compares the average values for every metric in either one or
two sets of archives, in a given time window, for changes that are
likely to be of interest when searching for performance regressions.
The archive specifiers archive1 and archive2 may be comma-separated
lists of names, each of which may be the base name of an archive or
the name of a directory containing one or more archives. Each archive
in the resulting set of archives must have been previously created
using pmlogger(1). The pmlogsummary(1) utility is used to obtain the
average values used for comparison.
There are two sorts of invocation of the tool: with either one or two
sets of archives.
In the first case, the only sensible command line requires use of all
four time window arguments. These are specified using the same time
window format described in PCPIntro(1), and are -S/--start and
-T/--finish for the start and end times of the first time window of
interest in the archive set, and -B/--before and -E/--end for the
start and end times of the second time window of interest.
In the second case, with two sets of archives, the -B/--before and
-E/--end options might be unnecessary. This might be the case, for
example, when comparing the same time window of two consecutive days
(usually two separate sets of archives), or a time window on the same
day of different weeks.
In either case, pmdiff produces a sorted summary of those metrics in
the specified window whose values have deviated the most from a
minimal threshold. The level of deviation is calculated by dividing
the average value of each metric in both logs, and then calculating
whether the ratio falls outside of a range considered normal. This
ratio can be adjusted using the -q/--threshold option, and by default
it is 2 (i.e. report all metrics with average values that have more
than doubled in the two time windows or more than halved in the two
time windows).
If the baseline value is zero and the comparison value is non-zero,
the ratio is reported as ``|+|'' (infinitely large). If the
comparison value is zero and the baseline value is non-zero, the
ratio is reported as ``|-|'' (infinitely small).
Reported metrics are sorted in ascending ratio order.
Should any metrics be present in one window but missing from the
other, a diagnostic will be displayed listing each missing metric and
the archive set from which it was missing.
The remaining options control the specific information to be
reported. Metrics with counter semantics are converted to rates
before being evaluated.
-p/--precision
Print all floating point numbers with precision digits after the
decimal place.
--skip-excluded
Cull the list of names of metrics being excluded from the
output.
--skip-missing
By default, pmdiff will report the names of any metrics that are
in one archive set but not the other. This option suppresses
that reporting.
-x Compare each metric in each archive set in the time windows
specified to a given egrep(1) pattern, excluding those that
match from the report output.
-X Allows a file to be specified which containing egrep(1) patterns
which are applied to the metric names to optionally exclude some
from the report.
-z Use the local timezone from the given archive set.
-Z/--timezone
Changes the timezone in the archive labels to timezone in the
format of the environment variable TZ as described in
environ(7).
$PCP_LOG_DIR/pmlogger/hostname
Default directory for PCP archives containing performance
metric values collected from the host hostname.
Environment variables with the prefix PCP_ are used to parameterize
the file and directory names used by PCP. On each installation, the
file /etc/pcp.conf contains the local values for these variables.
The $PCP_CONF variable may be used to specify an alternative
configuration file, as described in pcp.conf(5).
PCPIntro(1), pmlogger(1), pmlogsummary(1), egrep(1), pcp.conf(5) and
pcp.env(5).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page, or
you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a mail
to man-pages@man7.org
Performance Co-Pilot PCP PMDIFF(1)
Pages that refer to this page: pmrep(1)