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

NAME

6       pmdiff - compares archives and report significant differences
7

SYNOPSIS

9       pmdiff    [-d/--keep]    [-z/--hostzone]   [-p/--precision   precision]
10       [-q/--threshold thres]  [-S/--start  starttime]  [-T/--finish  endtime]
11       [-B/--begin   starttime]  [-E/--end  endtime]  [-x  metric]  [-X  file]
12       [--skip-excluded] [--skip-missing]  [-Z/--timezone  timezone]  archive1
13       [archive2]
14

DESCRIPTION

16       pmdiff  compares  the  average values for every metric in either one or
17       two sets of archives, in a given time  window,  for  changes  that  are
18       likely to be of interest when searching for performance regressions.
19
20       The  archive  specifiers  archive1  and archive2 may be comma-separated
21       lists of names, each of which may be the base name of an archive or the
22       name  of  a  directory containing one or more archives. Each archive in
23       the resulting set of archives must have been previously  created  using
24       pmlogger(1).  The pmlogsummary(1) utility is used to obtain the average
25       values used for comparison.
26
27       There are two sorts of invocation of the tool: with either one  or  two
28       sets of archives.
29
30       In  the  first case, the only sensible command line requires use of all
31       four time window arguments.  These are specified using  the  same  time
32       window   format  described  in  PCPIntro(1),  and  are  -S/--start  and
33       -T/--finish for the start and end times of the  first  time  window  of
34       interest in the archive set, and -B/--before and -E/--end for the start
35       and end times of the second time window of interest.
36
37       In the second case, with two sets  of  archives,  the  -B/--before  and
38       -E/--end  options  might  be  unnecessary.  This might be the case, for
39       example, when comparing the same time window of  two  consecutive  days
40       (usually  two  separate sets of archives), or a time window on the same
41       day of different weeks.
42
43       In either case, pmdiff produces a sorted summary of  those  metrics  in
44       the specified window whose values have deviated the most from a minimal
45       threshold.  The level of deviation is calculated by dividing the  aver‐
46       age value of each metric in both logs, and then calculating whether the
47       ratio falls outside of a range considered normal.  This  ratio  can  be
48       adjusted  using the -q/--threshold option, and by default it is 2 (i.e.
49       report all metrics with average values that have more than  doubled  in
50       the two time windows or more than halved in the two time windows).
51
52       If the baseline value is zero and the comparison value is non-zero, the
53       ratio is reported as ``|+|'' (infinitely  large).   If  the  comparison
54       value is zero and the baseline value is non-zero, the ratio is reported
55       as ``|-|'' (infinitely small).
56
57       Reported metrics are sorted in ascending ratio order.
58
59       Should any metrics be present in one window but missing from the other,
60       a  diagnostic will be displayed listing each missing metric and the ar‐
61       chive set from which it was missing.
62
63       The remaining options control the specific information to be  reported.
64       Metrics  with  counter  semantics  are  converted to rates before being
65       evaluated.
66
67       -p/--precision
68            Print all floating point numbers with precision digits  after  the
69            decimal place.
70
71       --skip-excluded
72            Cull the list of names of metrics being excluded from the output.
73
74       --skip-missing
75            By  default,  pmdiff will report the names of any metrics that are
76            in one archive set but not the other.  This option suppresses that
77            reporting.
78
79       -x   Compare each metric in each archive set in the time windows speci‐
80            fied to a given egrep(1) pattern, excluding those that match  from
81            the report output.
82
83       -X   Allows  a  file to be specified which containing egrep(1) patterns
84            which are applied to the metric names to optionally  exclude  some
85            from the report.
86
87       -z   Use the local timezone from the given archive set.
88
89       -Z/--timezone
90            Changes the timezone in the archive labels to timezone in the for‐
91            mat of the environment variable TZ as described in environ(7).
92

FILES

94       $PCP_LOG_DIR/pmlogger/hostname
95                 Default directory for  PCP  archives  containing  performance
96                 metric values collected from the host hostname.
97

PCP ENVIRONMENT

99       Environment variables with the prefix PCP_ are used to parameterize the
100       file and directory names used by PCP.  On each installation,  the  file
101       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
102       $PCP_CONF variable may be used to specify an alternative  configuration
103       file, as described in pcp.conf(5).
104

SEE ALSO

106       PCPIntro(1),  pmlogger(1),  pmlogsummary(1),  egrep(1), pcp.conf(5) and
107       pcp.env(5).
108
109
110
111Performance Co-Pilot                  PCP                            PMDIFF(1)
Impressum