NAME

       pmdiff - compares archives and report significant differences

SYNOPSIS

       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]

DESCRIPTION

       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).

FILES

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

PCP ENVIRONMENT

       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).

SEE ALSO

       PCPIntro(1), pmlogger(1), pmlogsummary(1), egrep(1), pcp.conf(5) and pcp.env(5).