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  archives,  in  a
       given  time  window,  for  changes  that  are  likely to be of interest when searching for
       performance regressions.

       The archive log has the base name archive and 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 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, 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 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 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 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 but
            not the other.  This option suppresses that reporting.

       -x   Compare each metric in each archive 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 archives.

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