Code

Imported upstream version 1.2.26
[pkg-rrdtool.git] / doc / rrdgraph_graph.1
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "RRDGRAPH_GRAPH 1"
132 .TH RRDGRAPH_GRAPH 1 "2007-11-20" "1.2.26" "rrdtool"
133 .SH "NAME"
134 rrdgraph_graph \- rrdtool graph command reference
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
138 .PP
139 \&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR
140 .PP
141 \&\fB\s-1COMMENT\s0\fR\fB:\fR\fItext\fR
142 .PP
143 \&\fB\s-1VRULE\s0\fR\fB:\fR\fItime\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR]
144 .PP
145 \&\fB\s-1HRULE\s0\fR\fB:\fR\fIvalue\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR]
146 .PP
147 \&\fB\s-1LINE\s0\fR[\fIwidth\fR]\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]
148 .PP
149 \&\fB\s-1AREA\s0\fR\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]
150 .PP
151 \&\fB\s-1TICK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIrrggbb\fR[\fIaa\fR][\fB:\fR\fIfraction\fR[\fB:\fR\fIlegend\fR]]
152 .PP
153 \&\fB\s-1SHIFT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIoffset\fR
154 .PP
155 \&\fB\s-1PRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
156 .PP
157 \&\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR (deprecated)
158 .PP
159 \&\fB\s-1STACK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR] (deprecated)
160 .SH "DESCRIPTION"
161 .IX Header "DESCRIPTION"
162 These instructions allow you to generate your image or report.
163 If you don't use any graph elements, no graph is generated.
164 Similarly, no report is generated if you don't use print options.
165 .SH "PRINT"
166 .IX Header "PRINT"
167 .IP "\fB\s-1PRINT:\s0\fR\fIvname\fR\fB:\fR\fIformat\fR[\fB:strftime\fR]" 4
168 .IX Item "PRINT:vname:format[:strftime]"
169 Depending on the context, either the value component or the time
170 component of a \fB\s-1VDEF\s0\fR is printed using \fIformat\fR. It is an error
171 to specify a \fIvname\fR generated by a \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR.
172 .Sp
173 Any text in \fIformat\fR is printed literally with one exception:
174 The percent character introduces a formatter string. This string
175 can be:
176 .Sp
177 For printing values:
178 .RS 4
179 .IP "\fB%%\fR" 4
180 .IX Item "%%"
181 just prints a literal '%' character
182 .IP "\fB%#.#le\fR" 4
183 .IX Item "%#.#le"
184 prints numbers like 1.2346e+04. The optional integers # denote field
185 width and decimal precision.
186 .IP "\fB%#.#lf\fR" 4
187 .IX Item "%#.#lf"
188 prints numbers like 12345.6789, with optional field width
189 and precision.
190 .IP "\fB%s\fR" 4
191 .IX Item "%s"
192 place this after \fB%le\fR, \fB%lf\fR or \fB%lg\fR. This will be replaced by the
193 appropriate \s-1SI\s0 magnitude unit and the value will be scaled
194 accordingly (123456 \-> 123.456 k).
195 .IP "\fB%S\fR" 4
196 .IX Item "%S"
197 is similar to \fB%s\fR. It does, however, use a previously defined
198 magnitude unit. If there is no such unit yet, it tries to define
199 one (just like \fB%s\fR) unless the value is zero, in which case the magnitude
200 unit stays undefined. Thus, formatter strings using \fB%S\fR and no \fB%s\fR
201 will all use the same magnitude unit except for zero values.
202 .RE
203 .RS 4
204 .Sp
205 If you \s-1PRINT\s0 a \s-1VDEF\s0 value, you can also print the time associated with it by appending the string
206 \&\fB:strftime\fR to the format. Note that rrdtool uses the strftime function of your OSs clibrary. This means that
207 the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
208 conversion specifiers usually supported across the board. 
209 .IP "\fB%a\fR" 4
210 .IX Item "%a"
211 The abbreviated weekday name according to the current locale.
212 .IP "\fB%A\fR" 4
213 .IX Item "%A"
214 The full weekday name according to the current locale.
215 .IP "\fB%b\fR" 4
216 .IX Item "%b"
217 The abbreviated month name according to the current locale.
218 .IP "\fB%B\fR" 4
219 .IX Item "%B"
220 The full month name according to the current locale.
221 .IP "\fB%c\fR" 4
222 .IX Item "%c"
223 The preferred date and time representation for the current locale.
224 .IP "\fB%d\fR" 4
225 .IX Item "%d"
226 The day of the month as a decimal number (range 01 to 31).
227 .IP "\fB%H\fR" 4
228 .IX Item "%H"
229 The hour as a decimal number using a 24\-hour clock (range 00 to 23).
230 .IP "\fB%I\fR" 4
231 .IX Item "%I"
232 The hour as a decimal number using a 12\-hour clock (range 01 to 12).
233 .IP "\fB%j\fR" 4
234 .IX Item "%j"
235 The day of the year as a decimal number (range 001 to 366).
236 .IP "\fB%m\fR" 4
237 .IX Item "%m"
238 The month as a decimal number (range 01 to 12).
239 .IP "\fB%M\fR" 4
240 .IX Item "%M"
241 The minute as a decimal number (range 00 to 59).
242 .IP "\fB%p\fR" 4
243 .IX Item "%p"
244 Either `\s-1AM\s0' or `\s-1PM\s0' according to the given time value, or the corresponding
245 strings for the current locale.  Noon is treated as `pm' and midnight as
246 `am'.  Note that in many locales and `pm' notation is unsupported and in
247 such cases \f(CW%p\fR will return an empty string.
248 .IP "\fB%S\fR" 4
249 .IX Item "%S"
250 The second as a decimal number (range 00 to 61).
251 .IP "\fB%U\fR" 4
252 .IX Item "%U"
253 The  week  number  of  the current year as a decimal number, range 00 to 53, starting with the
254 first Sunday as the first day of week 01. See also \f(CW%V\fR and \f(CW%W\fR.
255 .IP "\fB%V\fR" 4
256 .IX Item "%V"
257 The \s-1ISO\s0 8601:1988 week number of the current year as a decimal number, range 01 to  53,  where
258 week  1 is the first week that has at least 4 days in the current year, and with Monday as the
259 first day of the week. See also \f(CW%U\fR and \f(CW%W\fR.
260 .IP "\fB%w\fR" 4
261 .IX Item "%w"
262 The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also \f(CW%u\fR.
263 .IP "\fB%W\fR" 4
264 .IX Item "%W"
265 The week number of the current year as a decimal number, range 00 to  53,  starting  with  the
266 first Monday as the first day of week 01.
267 .IP "\fB%x\fR" 4
268 .IX Item "%x"
269 The preferred date representation for the current locale without the time.
270 .IP "\fB%X\fR" 4
271 .IX Item "%X"
272 The preferred time representation for the current locale without the date.
273 .IP "\fB%y\fR" 4
274 .IX Item "%y"
275 The year as a decimal number without a century (range 00 to 99).
276 .IP "\fB%Y\fR" 4
277 .IX Item "%Y"
278 The year as a decimal number including the century.
279 .IP "\fB%Z\fR" 4
280 .IX Item "%Z"
281 The time zone or name or abbreviation.
282 .IP "\fB%%\fR" 4
283 .IX Item "%%"
284 A literal `%' character.
285 .RE
286 .RS 4
287 .RE
288 .IP "\fB\s-1PRINT:\s0\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR" 4
289 .IX Item "PRINT:vname:CF:format"
290 \&\fIDeprecated. Use the new form of this command in new scripts.\fR
291 The first form of this command is to be used with \fB\s-1CDEF\s0\fR \fIvname\fRs.
292 .SH "GRAPH"
293 .IX Header "GRAPH"
294 .IP "\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIformat\fR" 4
295 .IX Item "GPRINT:vname:format"
296 This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
297 .IP "\fB\s-1GPRINT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fI\s-1CF\s0\fR\fB:\fR\fIformat\fR" 4
298 .IX Item "GPRINT:vname:CF:format"
299 \&\fIDeprecated. Use the new form of this command in new scripts.\fR
300 This is the same as \f(CW\*(C`PRINT\*(C'\fR, but printed inside the graph.
301 .IP "\fB\s-1COMMENT\s0\fR\fB:\fR\fItext\fR" 4
302 .IX Item "COMMENT:text"
303 Text is printed literally in the legend section of the graph. Note that in
304 RRDtool 1.2 you have to escape colons in \s-1COMMENT\s0 text in the same way you
305 have to escape them in \fB*PRINT\fR commands by writing \fB'\e:'\fR.
306 .IP "\fB\s-1VRULE\s0\fR\fB:\fR\fItime\fR\fB#\fR\fIcolor\fR [\fB:\fR\fIlegend\fR ]" 4
307 .IX Item "VRULE:time#color [:legend ]"
308 Draw a vertical line at \fItime\fR.  Its color is composed from three
309 hexadecimal numbers specifying the rgb color components (00 is off, \s-1FF\s0 is
310 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
311 printed in the legend section. \fItime\fR may be a number or a variable
312 from a \fB\s-1VDEF\s0\fR. It is an error to use \fIvname\fRs from \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR here.
313 .IP "\fB\s-1HRULE\s0\fR\fB:\fR\fIvalue\fR\fB#\fR\fIcolor\fR [ :\fIlegend\fR ]" 4
314 .IX Item "HRULE:value#color [ :legend ]"
315 Draw a horizontal line at \fIvalue\fR.  \s-1HRULE\s0 acts much like \s-1LINE\s0 except that
316 will have no effect on the scale of the graph. If a \s-1HRULE\s0 is outside the
317 graphing area it will just not be visible.
318 .IP "\fB\s-1LINE\s0\fR[\fIwidth\fR]\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]" 4
319 .IX Item "LINE[width]:value[#color][:[legend][:STACK]]"
320 Draw a line of the specified width onto the graph. \fIwidth\fR can be a
321 floating point number. If the color is not specified, the drawing is done
322 \&'invisibly'. This is useful when stacking something else on top of this
323 line. Also optional is the legend box and string which will be printed in
324 the legend section if specified. The \fBvalue\fR can be generated by \fB\s-1DEF\s0\fR,
325 \&\fB\s-1VDEF\s0\fR, and \fB\s-1CDEF\s0\fR.  If the optional \fB\s-1STACK\s0\fR modifier is used, this line
326 is stacked on top of the previous element which can be a \fB\s-1LINE\s0\fR or an
327 \&\fB\s-1AREA\s0\fR.
328 .Sp
329 When you do not specify a color, you cannot specify a legend.  Should
330 you want to use \s-1STACK\s0, use the \*(L"LINEx:<value>::STACK\*(R" form.
331 .IP "\fB\s-1AREA\s0\fR\fB:\fR\fIvalue\fR[\fB#\fR\fIcolor\fR][\fB:\fR[\fIlegend\fR][\fB:STACK\fR]]" 4
332 .IX Item "AREA:value[#color][:[legend][:STACK]]"
333 See \fB\s-1LINE\s0\fR, however the area between the x\-axis and the line will
334 be filled.
335 .IP "\fB\s-1TICK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIrrggbb\fR[\fIaa\fR][\fB:\fR\fIfraction\fR[\fB:\fR\fIlegend\fR]]" 4
336 .IX Item "TICK:vname#rrggbb[aa][:fraction[:legend]]"
337 Plot a tick mark (a vertical line) for each value of \fIvname\fR that is
338 non-zero and not *UNKNOWN*. The \fIfraction\fR argument specifies the length of
339 the tick mark as a fraction of the y\-axis; the default value is 0.1 (10% of
340 the axis). Note that the color specification is not optional. The \s-1TICK\s0 marks normaly
341 start at the lower edge of the graphing area. If the fraction is negative they start
342 at the upper border of the graphing area.
343 .IP "\fB\s-1SHIFT\s0\fR\fB:\fR\fIvname\fR\fB:\fR\fIoffset\fR" 4
344 .IX Item "SHIFT:vname:offset"
345 Using this command \fBRRDtool\fR will graph the following elements
346 with the specified offset.  For instance, you can specify an
347 offset of (\ 7*24*60*60\ =\ )\ 604'800\ seconds to \*(L"look back\*(R" one
348 week. Make sure to tell the viewer of your graph you did this ...
349 As with the other graphing elements, you can specify a number or
350 a variable here.
351 .IP "\fB\s-1STACK\s0\fR\fB:\fR\fIvname\fR\fB#\fR\fIcolor\fR[\fB:\fR\fIlegend\fR]" 4
352 .IX Item "STACK:vname#color[:legend]"
353 \&\fIDeprecated.  Use the \f(BI\s-1STACK\s0\fI modifiers on the other commands.\fR
354 .PP
355 \&\fBSome notes on stacking\fR
356 .PP
357 When stacking, an element is not placed above the X\-axis but rather
358 on top of the previous element.  There must be something to stack
359 upon.
360 .PP
361 You can use an \fBinvisible\fR \s-1LINE\s0 or \s-1AREA\s0 to stacked upon.
362 .PP
363 An \fBunknown\fR value makes the entire stack unknown from that moment on.
364 You don't know where to begin (the unknown value) and therefore do
365 not know where to end.
366 .PP
367 If you want to make sure you will be displaying a certain variable,
368 make sure never to stack upon the unknown value.  Use a \s-1CDEF\s0 instruction
369 with \fB\s-1IF\s0\fR and \fB\s-1UN\s0\fR to do so.
370 .SH "NOTES on legend arguments"
371 .IX Header "NOTES on legend arguments"
372 .Sh "Escaping the colon"
373 .IX Subsection "Escaping the colon"
374 A colon ':' in a \fIlegend\fR argument will mark the end of the
375 legend. To enter a ':' as part of a legend, the colon must be escaped
376 with a backslash '\e:'.  Beware that many environments process
377 backslashes themselves, so it may be necessary to write two
378 backslashes in order to one being passed onto rrd_graph.
379 .Sh "String Formatting"
380 .IX Subsection "String Formatting"
381 The text printed below the actual graph can be formatted by appending special
382 escape characters at the end of a text. When ever such a character occurs,
383 all pending text is pushed onto the graph according to the character
384 specified.
385 .PP
386 Valid markers are: \fB\ej\fR for justified, \fB\el\fR for left aligned, \fB\er\fR for
387 right aligned, and \fB\ec\fR for centered. In the next section there is an
388 example showing how to use centered formatting.
389 .PP
390 \&\fB\en\fR is a valid alias for \fB\el\fR since incomplete parsing in earlier
391 versions of rrdtool lead to this behaviour and a number of people has been using it.
392 .PP
393 Normally there are two space characters inserted between every two items
394 printed into the graph. The space following a string can be suppressed by
395 putting a \fB\eg\fR at the end of the string. The \fB\eg\fR also ignores any space
396 inside the string if it is at the very end of the string. This can be used
397 in connection with \fB%s\fR to suppress empty unit strings.
398 .PP
399 .Vb 1
400 \& GPRINT:a:MAX:%lf%s\eg
401 .Ve
402 .PP
403 A special case is \s-1COMMENT:\s0\fB\es\fR which inserts some additional vertical space
404 before placing the next row of legends.
405 .PP
406 If you are using the proportional font in your graph, you can use tab
407 characters or the sequence \fB\et\fR to line-up legend elements. Note that
408 the tabs inserted are relative to the start of the current legend
409 element!
410 .SH "SEE ALSO"
411 .IX Header "SEE ALSO"
412 rrdgraph gives an overview of how \fBrrdtool graph\fR works.
413 rrdgraph_data describes \fB\s-1DEF\s0\fR,\fB\s-1CDEF\s0\fR and \fB\s-1VDEF\s0\fR in detail.
414 rrdgraph_rpn describes the \fB\s-1RPN\s0\fR language used in the \fB?DEF\fR statements.
415 rrdgraph_graph page describes all of the graph and print functions.
416 .PP
417 Make sure to read rrdgraph_examples for tips&tricks.
418 .SH "AUTHOR"
419 .IX Header "AUTHOR"
420 Program by Tobias Oetiker <tobi@oetiker.ch>
421 .PP
422 This manual page by Alex van den Bogaerdt <alex@ergens.op.het.net>