# pmdiff

## NAME



           **pmdiff** - compares archives and report significant differences
    


## SYNOPSIS



           **pmdiff**[**-dzV?**]  [**-B** _starttime_] [**-E** _endtime_] [**-p** _precision_] [**-q**
           _thres_] [**-S** _starttime_] [**--skip-excluded**] [**--skip-missing**] [**-T**
           _endtime_] [**-x** _metric_] [**-X** _file_] [**-Z** _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.
    
           Metrics with counter semantics are converted to rates before being
           evaluated.
    


## OPTIONS



           The available command line options are:
    
           **-d** , **--keep**
                Debug mode, keep intermediate files.
    
           **-B** _time_ , **--begin** =_time_
                Start _time_ for the second time window.
    
           **-E** _time_ , **--end** =_time_
                End _time_ for the second time window.
    
           **-p** _precision_ , **--precision** =_precision_
                Print all floating point numbers with _precision_ digits after
                the decimal place.
    
           **-q** _threshold_ , **--threshold** =_threshold_
                Change the _threshold_ for interesting metrics, see above for
                more details.
    
           **-S** _time_ , **--start** =_time_
                Start _time_ of the first time window.
    
           **-T** _time_ , **--finish** =_time_
                End _time_ of the first time window.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-x** _metric_
                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** _file_
                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** , **--hostzone**
                Use the local timezone from the given archive set.
    
           **-Z** _timezone_ , **--timezone** =_timezone_
                Changes the timezone in the archive labels to _timezone_ in the
                format of the environment variable **TZ** as described in
                environ(7).
    
           **-?** , **--help**
                Display usage message and exit.
    
           **--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.
    


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


* * *