1PMDIFF(1)                   General Commands Manual                  PMDIFF(1)
2
3
4

NAME

6       pmdiff - compares archives and report significant differences
7

SYNOPSIS

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

DESCRIPTION

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
18       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
25       There are two sorts of invocation of the tool: with either one  or  two
26       sets of archives.
27
28       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
35       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
41       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
50       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
55       Reported metrics are sorted in ascending ratio order.
56
57       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
61       Metrics with counter semantics are  converted  to  rates  before  being
62       evaluated.
63

OPTIONS

65       The available command line options are:
66
67       -d, --keep
68            Debug mode, keep intermediate files.
69
70       -B time, --begin=time
71            Start time for the second time window.
72
73       -E time, --end=time
74            End time for the second time window.
75
76       -p precision, --precision=precision
77            Print  all  floating point numbers with precision digits after the
78            decimal place.
79
80       -q threshold, --threshold=threshold
81            Change the threshold for interesting metrics, see above  for  more
82            details.
83
84       -S time, --start=time
85            Start time of the first time window.
86
87       -T time, --finish=time
88            End time of the first time window.
89
90       -V, --version
91            Display version number and exit.
92
93       -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
98       -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
103       -z, --hostzone
104            Use the local timezone from the given archive set.
105
106       -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
110       -?, --help
111            Display usage message and exit.
112
113       --skip-excluded
114            Cull the list of names of metrics being excluded from the output.
115
116       --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

FILES

122       $PCP_LOG_DIR/pmlogger/<hostname>
123                 Default directory for  PCP  archives  containing  performance
124                 metric values collected from the host hostname.
125

PCP ENVIRONMENT

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

SEE ALSO

134       PCPIntro(1),  pmlogger(1),  pmlogsummary(1),  egrep(1), pcp.conf(5) and
135       pcp.env(5).
136
137
138
139Performance Co-Pilot                  PCP                            PMDIFF(1)
Impressum