index 80fd8424737380df6c130dbcbe63847ac1f769d7..2adcb2ddd17cf4f10288d4df1a3522abbe574bc9 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.1801 (Pod::Simple 3.08)
.\"
.\" Standard preamble:
.\" ========================================================================
.\"
.\" 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
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
. ds R" ''
'br\}
.\"
. 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
.\" 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.
.\" 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
.\}
. 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.
.\"
.\" 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"
.\" ========================================================================
.\"
.IX Title "RRDGRAPH_EXAMPLES 1"
-.TH RRDGRAPH_EXAMPLES 1 "2008-02-17" "1.2.27" "rrdtool"
+.TH RRDGRAPH_EXAMPLES 1 "2009-05-10" "1.3.999" "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"
.SH "NAME"
rrdgraph_examples \- Examples for rrdtool graph
.SH "SYNOPSIS"
ready because comments are intermixed with the examples.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
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
.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
\& 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
.IX Subsection "Nicely formatted legend section"
.Vb 10
\& DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE
\& COMMENT:"Maximum "
\& COMMENT:"Average "
\& COMMENT:"Minimum "
\& COMMENT:"Maximum "
\& COMMENT:"Average "
\& COMMENT:"Minimum "
-.Ve
-.PP
-.Vb 11
+\&
\& COMMENT:"95th percentile\el"
\& AREA:ds0bits#00C000:"Inbound "
\& GPRINT:ds0max:"%6.2lf %Sbps"
\& 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
\& 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
.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
.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
.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
\& 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
.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
\& 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.
.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
.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