![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 163f34fcea48c4f5496918403a0547c81469c108..2380fff04ccc89f0c23f8388dc9758f1eed603cf 100644 (file)
--- a/doc/rrdgraph_examples.1
+++ b/doc/rrdgraph_examples.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "RRDGRAPH_EXAMPLES 1"
-.TH RRDGRAPH_EXAMPLES 1 "2007-11-20" "1.2.26" "rrdtool"
+.TH RRDGRAPH_EXAMPLES 1 "2013-05-23" "1.4.8" "rrdtool"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
rrdgraph_examples \- Examples for rrdtool graph
.SH "SYNOPSIS"
ready because comments are intermixed with the examples.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
-.Sh "Data with multiple resolutions"
+.SS "Data with multiple resolutions"
.IX Subsection "Data with multiple resolutions"
.Vb 7
\& \-\-end now \-\-start end\-120000s \-\-width 400
\& LINE1:ds0b#00CCFF:"resolution 1800 seconds per interval\el"
\& LINE1:ds0c#FF00FF:"resolution 7200 seconds per interval\el"
.Ve
-.Sh "Nicely formatted legend section"
+.SS "Nicely formatted legend section"
.IX Subsection "Nicely formatted legend section"
.Vb 10
\& DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
\& COMMENT:"Maximum "
\& COMMENT:"Average "
\& COMMENT:"Minimum "
-.Ve
-.PP
-.Vb 11
+\&
\& COMMENT:"95th percentile\el"
\& AREA:ds0bits#00C000:"Inbound "
\& GPRINT:ds0max:"%6.2lf %Sbps"
\& GPRINT:ds1min:"%6.2lf %Sbps"
\& GPRINT:ds1pct:"%6.2lf %Sbps\el"
.Ve
-.Sh "Offsetting a line on the y\-axis"
+.SS "Offsetting a line on the y\-axis"
.IX Subsection "Offsetting a line on the y-axis"
Depending on your needs you can do this in two ways:
.IP "\(bu" 4
.Vb 1
\& LINE1:data#FF0000:"Data with offset":STACK
.Ve
-.Sh "Time ranges"
+.SS "Drawing dashed lines"
+.IX Subsection "Drawing dashed lines"
+Also works for \s-1HRULE\s0 and \s-1VRULE\s0
+.IP "\(bu" 4
+default style: \- \- \- \- \-
+ LINE1:data#FF0000:\*(L"dashed line\*(R":dashes
+.IP "\(bu" 4
+more fancy style with offset: \- \- \-\-\- \- \-\-\- \-
+ LINE1:data#FF0000:\*(L"another dashed line\*(R":dashes=15,5,5,10:dash\-offset=10
+.SS "Time ranges"
.IX Subsection "Time ranges"
.Vb 6
\& Last four weeks: \-\-start end\-4w \-\-end 00:00
\& Last 24 hours: <nothing at all>
\& Yesterday: \-\-end 00:00
.Ve
-.Sh "Viewing the current and previous week together"
+.SS "Viewing the current and previous week together"
.IX Subsection "Viewing the current and previous week together"
.Vb 3
\& \-\-end now \-\-start end\-1w
\& AREA:lastweek#0000FF:Last\e week
\& LINE1:thisweek#FF0000:This\e week
.Ve
+.SS "Aberrant Behaviour Detection"
+.IX Subsection "Aberrant Behaviour Detection"
+If the specialized function \fBRRAs\fR exist for aberrant behavior detection, they
+can be used to generate the graph of a time series with confidence bands and
+failures.
+.PP
+.Vb 10
+\& rrdtool graph example.png \e
+\& DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \e
+\& DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \e
+\& DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \e
+\& DEF:fail=monitor.rrd:ifOutOctets:FAILURES \e
+\& TICK:fail#ffffa0:1.0:"Failures\e: Average bits out" \e
+\& CDEF:scaledobs=obs,8,* \e
+\& CDEF:upper=pred,dev,2,*,+ \e
+\& CDEF:lower=pred,dev,2,*,\- \e
+\& CDEF:scaledupper=upper,8,* \e
+\& CDEF:scaledlower=lower,8,* \e
+\& LINE2:scaledobs#0000ff:"Average bits out" \e
+\& LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \e
+\& LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out"
+.Ve
+.PP
+This example generates a graph of the data series in blue (\s-1LINE2\s0 with the scaledobs
+virtual data source), confidence bounds in red (scaledupper and scaledlower virtual
+data sources), and potential failures (i.e. potential aberrant aberrant behavior)
+marked by vertical yellow lines (the fail data source).
+.PP
+The raw data comes from an \s-1AVERAGE\s0 \fB\s-1RRA\s0\fR, the finest resolution of the observed
+time series (one consolidated data point per primary data point). The predicted
+(or smoothed) values are stored in the \s-1HWPREDICT\s0 \fB\s-1RRA\s0\fR. The predicted deviations
+(think standard deviation) values are stored in the \s-1DEVPREDICT\s0 \fB\s-1RRA\s0\fR. Finally,
+the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR contains indicators, with 1 denoting a potential failure.
+.PP
+All of the data is rescaled to bits (instead of Octets) by multiplying by 8.
+The confidence bounds are computed by an offset of 2 deviations both above
+and below the predicted values (the CDEFs upper and lower). Vertical lines
+indicated potential failures are graphed via the \s-1TICK\s0 graph element, which
+converts non-zero values in an \fB\s-1RRA\s0\fR into tick marks. Here an axis-fraction
+argument of 1.0 means the tick marks span the entire y\-axis, and hence become
+vertical lines on the graph.
+.PP
+The choice of 2 deviations (a scaling factor) matches the default used internally
+by the \s-1FAILURES\s0 \fB\s-1RRA\s0\fR. If the internal value is changed (see rrdtune), this
+graphing command should be changed to be consistent.
+.PP
+\fIA note on data reduction:\fR
+.IX Subsection "A note on data reduction:"
+.PP
+The \fBrrdtool\fR \fIgraph\fR command is designed to plot data at a specified temporal
+resolution, regardless of the actually resolution of the data in the \s-1RRD\s0 file.
+This can present a problem for the specialized consolidation functions which
+maintain a one-to-one mapping between primary data points and consolidated
+data points. If a graph insists on viewing the contents of these \fBRRAs\fR on a
+coarser temporal scale, the \fIgraph\fR command tries to do something intelligent,
+but the confidence bands and failures no longer have the same meaning and may
+be misleading.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
rrdgraph gives an overview of how \fBrrdtool graph\fR works.
rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fBxDEF\fR statements.
rrdgraph_graph page describes all the graph and print functions.
-.PP
-Make sure to read rrdgraph_examples for tips&tricks.
.SH "AUTHOR"
.IX Header "AUTHOR"
Program by Tobias Oetiker <tobi@oetiker.ch>
.PP
-This manual page by Alex van den Bogaerdt <alex@ergens.op.het.net>
+This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl>
+with corrections and/or additions by several people