1PMDIFF(1) General Commands Manual PMDIFF(1)
2
6 pmdiff - compares archives and report significant differences
7
9 pmdiff [-dzV?] [-B starttime] [-E endtime] [-p precision] [-q thres]
10 [-S starttime] [-T endtime] [-x metric] [-X file] [-Z timezone]
11 [--skip-excluded] [--skip-missing] archive1 [archive2]
12
14 pmdiff compares the average values for every metric in either one or
15 two sets of archives, in a given time window, for changes that are
16 likely to be of interest when searching for performance regressions.
17 The archive specifiers archive1 and archive2 may be comma-separated
19 lists of names, each of which may be the base name of an archive or the
20 name of a directory containing one or more archives. Each archive in
21 the resulting set of archives must have been previously created using
22 pmlogger(1). The pmlogsummary(1) utility is used to obtain the average
23 values used for comparison.
24 There are two sorts of invocation of the tool: with either one or two
26 sets of archives.
27 In the first case, the only sensible command line requires use of all
29 four time window arguments. These are specified using the same time
30 window format described in PCPIntro(1), and are -S/--start and
31 -T/--finish for the start and end times of the first time window of
32 interest in the archive set, and -B/--before and -E/--end for the start
33 and end times of the second time window of interest.
34 In the second case, with two sets of archives, the -B/--before and
36 -E/--end options might be unnecessary. This might be the case, for
37 example, when comparing the same time window of two consecutive days
38 (usually two separate sets of archives), or a time window on the same
39 day of different weeks.
40 In either case, pmdiff produces a sorted summary of those metrics in
42 the specified window whose values have deviated the most from a minimal
43 threshold. The level of deviation is calculated by dividing the aver‐
44 age value of each metric in both logs, and then calculating whether the
45 ratio falls outside of a range considered normal. This ratio can be
46 adjusted using the -q/--threshold option, and by default it is 2 (i.e.
47 report all metrics with average values that have more than doubled in
48 the two time windows or more than halved in the two time windows).
49 If the baseline value is zero and the comparison value is non-zero, the
51 ratio is reported as ``|+|'' (infinitely large). If the comparison
52 value is zero and the baseline value is non-zero, the ratio is reported
53 as ``|-|'' (infinitely small).
54 Reported metrics are sorted in ascending ratio order.
56 Should any metrics be present in one window but missing from the other,
58 a diagnostic will be displayed listing each missing metric and the ar‐
59 chive set from which it was missing.
60 Metrics with counter semantics are converted to rates before being
62 evaluated.
63
65 The available command line options are:
66 -d, --keep
68 Debug mode, keep intermediate files.
69 -B time, --begin=time
71 Start time for the second time window.
72 -E time, --end=time
74 End time for the second time window.
75 -p precision, --precision=precision
77 Print all floating point numbers with precision digits after the
78 decimal place.
79 -q threshold, --threshold=threshold
81 Change the threshold for interesting metrics, see above for more
82 details.
83 -S time, --start=time
85 Start time of the first time window.
86 -T time, --finish=time
88 End time of the first time window.
89 -V, --version
91 Display version number and exit.
92 -x metric
94 Compare each metric in each archive set in the time windows speci‐
95 fied to a given egrep(1) pattern, excluding those that match from
96 the report output.
97 -X file
99 Allows a file to be specified which containing egrep(1) patterns
100 which are applied to the metric names to optionally exclude some
101 from the report.
102 -z, --hostzone
104 Use the local timezone from the given archive set.
105 -Z timezone, --timezone=timezone
107 Changes the timezone in the archive labels to timezone in the for‐
108 mat of the environment variable TZ as described in environ(7).
109 -?, --help
111 Display usage message and exit.
112 --skip-excluded
114 Cull the list of names of metrics being excluded from the output.
115 --skip-missing
117 By default, pmdiff will report the names of any metrics that are
118 in one archive set but not the other. This option suppresses that
119 reporting.
120
122 $PCP_LOG_DIR/pmlogger/<hostname>
123 Default directory for PCP archives containing performance
124 metric values collected from the host hostname.
125
127 Environment variables with the prefix PCP_ are used to parameterize the
128 file and directory names used by PCP. On each installation, the file
129 /etc/pcp.conf contains the local values for these variables. The
130 $PCP_CONF variable may be used to specify an alternative configuration
131 file, as described in pcp.conf(5).
132
134 PCPIntro(1), pmlogger(1), pmlogsummary(1), egrep(1), pcp.conf(5) and
135 pcp.env(5).
136Performance Co-Pilot PCP PMDIFF(1)