1 files changed, 167 insertions, 0 deletions
diff --git a/man/man1/pmdiff.1 b/man/man1/pmdiff.1
new file mode 100644
index 0000000..143cf36
--- /dev/null
+++ b/man/man1/pmdiff.1
@@ -0,0 +1,167 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013-2014 Red Hat.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 2 of the License, or (at your
+.\" option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+.\" for more details.
+.\" 
+.\" 
+.TH PMWTF 1 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3pmdiff\f1 \- compares archives and report significant differences
+.SH SYNOPSIS
+\f3pmdiff\f1
+[\f3\-d\f1/\f3--keep\f1]
+[\f3\-z\f1/\f3--hostzone\f1]
+[\f3\-p\f1/\f3--precision\f1 \f2precision\f1]
+[\f3\-q\f1/\f3--threshold\f1 \f2thres\f1]
+[\f3\-S\f1/\f3--start\f1 \f2starttime\f1]
+[\f3\-T\f1/\f3--finish\f1 \f2endtime\f1]
+[\f3\-B\f1/\f3--begin\f1 \f2starttime\f1]
+[\f3\-E\f1/\f3--end\f1 \f2endtime\f1]
+[\f3\-x\f1 \f2metric\f1]
+[\f3\-X\f1 \f2file\f1]
+[\f3--skip-excluded\f1]
+[\f3--skip-missing\f1]
+[\f3\-Z\f1/\f3--timezone\f1 \f2timezone\f1]
+\f2archive1\f1
+[\f2archive2\f1]
+.SH DESCRIPTION
+.B 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.
+.PP
+The archive log has the base name
+.I archive
+and must have been previously created using
+.BR pmlogger (1).
+The
+.BR pmlogsummary (1)
+utility is used to obtain the average values used for comparison.
+.PP
+There are two sorts of invocation of the tool: with either one or
+two archives.
+.PP
+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
+.BR PCPIntro (1),
+and are
+.BR \-S / \-\-start
+and
+.BR \-T / \-\-finish
+for the start and end times of the first time window of interest
+in the archive, and
+.BR \-B / \-\-before
+and
+.BR \-E / \-\-end
+for the start and end times of the second time window of interest.
+.PP
+In the second case, with two archives, the 
+.BR \-B / \-\-before
+and
+.BR \-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.
+.PP
+In either case,
+.B 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
+.BR \-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).
+.PP
+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.
+.PP
+The remaining options control the specific information to be reported.
+Metrics with counter semantics are converted to rates before being
+evaluated.
+.TP 5
+.BR \-p / \-\-precision
+Print all floating point numbers with 
+.I precision
+digits after the decimal place.
+.TP
+.B \-\-skip-excluded
+Cull the list of names of metrics being excluded from the output.
+.TP
+.B \-\-skip-missing
+By default,
+.B pmdiff
+will report the names of any metrics that are in one archive but not
+the other.
+This option suppresses that reporting.
+.TP
+.B \-x
+Compare each metric in each archive in the time windows specified
+to a given
+.BR egrep (1)
+pattern, excluding those that match from the report output.
+.TP
+.B \-X
+Allows a
+.IR file
+to be specified which containing
+.BR egrep (1)
+patterns which are applied to the metric names to optionally exclude
+some from the report.
+.TP
+.B \-z
+Use the local timezone from the given archives.
+.TP
+.BR \-Z / \-\-timezone
+Changes the timezone in the archive labels to
+.I timezone
+in the format of the environment variable
+.B TZ
+as described in
+.BR environ (5).
+.PP
+.SH FILES
+.PD 0
+.TP 10
+.BI $PCP_LOG_DIR/pmlogger/ hostname
+Default directory for PCP archives containing performance
+metric values collected from the host
+.IR hostname .
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.I /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR PCPIntro (1),
+.BR pmlogger (1),
+.BR pmlogsummary (1),
+.BR egrep (1),
+.BR pcp.conf (5)
+and
+.BR pcp.env (5).