1RRDGRAPH_GRAPH(1)                   rrdtool                  RRDGRAPH_GRAPH(1)
2
3
4

NAME

6       rrdgraph_graph - rrdtool graph command reference
7

SYNOPSIS

9       PRINT:vname:format[:strftime|:valstrftime|:valstrfduration]
10
11       GPRINT:vname:format
12
13       COMMENT:text
14
15       VRULE:time#color[:[legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]
16
17       HRULE:value#color[:[legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]
18
19       LINE[width]:value[#color][:[legend][:STACK][:skipscale][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]
20
21       AREA:value[#color][:[legend][:STACK][:skipscale]]
22
23       TICK:vname#rrggbb[aa][:fraction[:legend]]
24
25       SHIFT:vname:offset
26
27       TEXTALIGN:{left|right|justified|center}
28
29       PRINT:vname:CF:format (deprecated)
30
31       GPRINT:vname:CF:format (deprecated)
32
33       STACK:vname#color[:legend] (deprecated)
34

DESCRIPTION

36       These instructions allow you to generate your image or report.  If you
37       don't use any graph elements, no graph is generated.  Similarly, no
38       report is generated if you don't use print options.
39
40   PRINT
41       PRINT:vname:format[:strftime|:valstrftime|:valstrfduration]
42
43       Depending on the context, either the value component (no suffix,
44       valstrftime or valstrfduration) or the time component (strftime) of a
45       VDEF is printed using format. It is an error to specify a vname
46       generated by a DEF or CDEF.
47
48       Any text in format is printed literally with one exception: The percent
49       character introduces a formatter string. This string can be:
50
51       For printing values:
52
53       %%  just prints a literal '%' character
54
55       %#.#le
56           prints numbers like 1.2346e+04. The optional integers # denote
57           field width and decimal precision.
58
59       %#.#lf
60           prints numbers like 12345.6789 (%5.4lf), with optional field width
61           and precision.
62
63       %s  place this after %le, %lf or %lg. This will be replaced by the
64           appropriate SI magnitude unit and the value will be scaled
65           accordingly (123456 -> 123.456 k).
66
67       %S  is similar to %s. It does, however, use a previously defined
68           magnitude unit. If there is no such unit yet, it tries to define
69           one (just like %s) unless the value is zero, in which case the
70           magnitude unit stays undefined. Thus, formatter strings using %S
71           and no %s will all use the same magnitude unit except for zero
72           values.
73
74       If you PRINT a VDEF value, you can also print the time associated with
75       it by appending the string :strftime to the format. Note that RRDtool
76       uses the strftime function of your OSs C library. This means that the
77       conversion specifier may vary. Check the manual page if you are
78       uncertain. The following is a list of conversion specifiers usually
79       supported across the board. Formatting values interpreted as timestamps
80       with :valstrftime is done likewise.
81
82       %a  The abbreviated weekday name according to the current locale.
83
84       %A  The full weekday name according to the current locale.
85
86       %b  The abbreviated month name according to the current locale.
87
88       %B  The full month name according to the current locale.
89
90       %c  The preferred date and time representation for the current locale.
91
92       %d  The day of the month as a decimal number (range 01 to 31).
93
94       %H  The hour as a decimal number using a 24-hour clock (range 00 to
95           23).
96
97       %I  The hour as a decimal number using a 12-hour clock (range 01 to
98           12).
99
100       %j  The day of the year as a decimal number (range 001 to 366).
101
102       %m  The month as a decimal number (range 01 to 12).
103
104       %M  The minute as a decimal number (range 00 to 59).
105
106       %p  Either `AM' or `PM' according to the given time value, or the
107           corresponding strings for the current locale.  Noon is treated as
108           `pm' and midnight as `am'.  Note that in many locales a `pm'
109           notation is unsupported and in such cases %p will return an empty
110           string.
111
112       %s  The second as a decimal number (range 00 to 61).
113
114       %S  The seconds since the epoch (1.1.1970) (libc dependent non
115           standard!)
116
117       %U  The  week  number  of  the current year as a decimal number, range
118           00 to 53, starting with the first Sunday as the first day of week
119           01. See also %V and %W.
120
121       %V  The ISO 8601:1988 week number of the current year as a decimal
122           number, range 01 to  53,  where week  1 is the first week that has
123           at least 4 days in the current year, and with Monday as the first
124           day of the week. See also %U and %W.
125
126       %w  The day of the week as a decimal, range 0 to 6, Sunday being 0.
127           See also %u.
128
129       %W  The week number of the current year as a decimal number, range 00
130           to  53,  starting  with  the first Monday as the first day of week
131           01.
132
133       %x  The preferred date representation for the current locale without
134           the time.
135
136       %X  The preferred time representation for the current locale without
137           the date.
138
139       %y  The year as a decimal number without a century (range 00 to 99).
140
141       %Y  The year as a decimal number including the century.
142
143       %Z  The time zone or name or abbreviation.
144
145       %%  A literal `%' character.
146
147       Formatting values as duration is done using printf like conversion
148       specifications:
149
150        - All non-conversion specification chars are copied unchanged
151        - A conversion specification has format '%' [ ['0'] minwidth ] [ '.' precision ] conversion-specifier
152
153       With conversion-specifier being one of:
154
155       %   A raw '%' is output, width and precision are ignored
156
157       W   Number of weeks
158
159       d   Number of days, modulus number of weeks
160
161       D   Number of days
162
163       h   Number of hours, modulus number of days
164
165       H   Number of hours
166
167       m   Number of minutes, modulus number of hours
168
169       M   Number of minutes
170
171       s   Number of seconds, modulus number of minutes
172
173       S   Number of seconds
174
175       f   Number of milliseconds, modulus seconds
176
177       PRINT:vname:CF:format
178
179       Deprecated. Use the new form of this command in new scripts.  The first
180       form of this command is to be used with CDEF vnames.
181
182   GRAPH
183       GPRINT:vname:format
184
185       This is the same as "PRINT", but printed inside the graph.
186
187       GPRINT:vname:CF:format
188
189       Deprecated. Use the new form of this command in new scripts.  This is
190       the same as "PRINT", but printed inside the graph.
191
192       COMMENT:text
193
194       Text is printed literally in the legend section of the graph. Note that
195       in RRDtool 1.2 you have to escape colons in COMMENT text in the same
196       way you have to escape them in *PRINT commands by writing '\:'.
197
198       VRULE:time#color[:[legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]
199
200       Draw a vertical line at time.  Its color is composed from three
201       hexadecimal numbers specifying the rgb color components (00 is off, FF
202       is maximum) red, green and blue followed by an optional alpha.
203       Optionally, a legend box and string is printed in the legend section.
204       time may be a number or a variable from a VDEF. It is an error to use
205       vnames from DEF or CDEF here.  Dashed lines can be drawn using the
206       dashes modifier. See LINE for more details.
207
208       HRULE:value#color[:[legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]
209
210       Draw a horizontal line at value.  HRULE acts much like LINE except that
211       will have no effect on the scale of the graph. If a HRULE is outside
212       the graphing area it will just not be visible and it will not appear in
213       the legend by default.
214
215       LINE[width]:value[#color][:[legend][:STACK][:skipscale][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]
216
217       Draw a line of the specified width onto the graph. width can be a
218       floating point number. If the color is not specified, the drawing is
219       done 'invisibly'. This is useful when stacking something else on top of
220       this line. Also optional is the legend box and string which will be
221       printed in the legend section if specified. The value can be generated
222       by DEF, VDEF, and CDEF.  If the optional STACK modifier is used, this
223       line is stacked on top of the previous element which can be a LINE or
224       an AREA.
225
226       Normally the graphing function makes sure that the entire LINE or AREA
227       is visible in the chart. The scaling of the chart will be modified
228       accordingly if necessary. Any LINE or AREA can be excluded from this
229       process by adding the option skipscale.
230
231       The dashes modifier enables dashed line style. Without any further
232       options a symmetric dashed line with a segment length of 5 pixels will
233       be drawn. The dash pattern can be changed if the dashes= parameter is
234       followed by either one value or an even number (1, 2, 4, 6, ...) of
235       positive values. Each value provides the length of alternate on_s and
236       off_s portions of the stroke. The dash-offset parameter specifies an
237       offset into the pattern at which the stroke begins.
238
239       When you do not specify a color, you cannot specify a legend.  Should
240       you want to use STACK, use the "LINEx:<value>::STACK" form.
241
242       AREA:value[#color[#color2]][:[legend][:STACK][:skipscale][:gradheight=y]
243
244       See LINE, however the area between the x-axis and the line will be
245       filled.
246
247       If color2 is specified, the area will be filled with a gradient.
248
249       The gradheight parameter can create three different behaviors. If
250       gradheight > 0, then the gradient is a fixed height, starting at the
251       line going down.  If gradheight < 0, then the gradient starts at a
252       fixed height above the x-axis, going down to the x-axis.  If height ==
253       0, then the gradient goes from the line to x-axis.
254
255       The default value for gradheight is 50.
256
257       TICK:vname#rrggbb[aa][:fraction[:legend]]
258
259       Plot a tick mark (a vertical line) for each value of vname that is non-
260       zero and not *UNKNOWN*. The fraction argument specifies the length of
261       the tick mark as a fraction of the y-axis; the default value is 0.1
262       (10% of the axis). Note that the color specification is not optional.
263       The TICK marks normally start at the lower edge of the graphing area.
264       If the fraction is negative they start at the upper border of the
265       graphing area.
266
267       SHIFT:vname:offset
268
269       Using this command RRDtool will graph the following elements with the
270       specified offset.  For instance, you can specify an offset of
271       ( 7*24*60*60 = ) 604'800 seconds to "look back" one week. Make sure to
272       tell the viewer of your graph you did this ...  As with the other
273       graphing elements, you can specify a number or a variable here.
274
275       TEXTALIGN:{left|right|justified|center}
276
277       Labels are placed below the graph. When they overflow to the left, they
278       wrap to the next line. By default, lines are justified left and right.
279       The TEXTALIGN function lets you change this default. This is a command
280       and not an option, so that you can change the default several times in
281       your argument list.
282
283       STACK:vname#color[:legend]
284
285       Deprecated.  Use the STACK modifiers on the other commands instead!
286
287       Some notes on stacking
288
289       When stacking, an element is not placed above the X-axis but rather on
290       top of the previous element.  There must be something to stack upon.
291
292       You can use an invisible LINE or AREA to stacked upon.
293
294       An unknown value makes the entire stack unknown from that moment on.
295       You don't know where to begin (the unknown value) and therefore do not
296       know where to end.
297
298       If you want to make sure you will be displaying a certain variable,
299       make sure never to stack upon the unknown value.  Use a CDEF
300       instruction with IF and UN to do so.
301

NOTES on legend arguments

303   Escaping the colon
304       A colon ':' in a legend argument will mark the end of the legend. To
305       enter a ':' as part of a legend, the colon must be escaped with a
306       backslash '\:'.  Beware that many environments process backslashes
307       themselves, so it may be necessary to write two backslashes in order to
308       one being passed onto rrd_graph.
309
310   String Formatting
311       The text printed below the actual graph can be formatted by appending
312       special escape characters at the end of a text. Whenever such a
313       character occurs, all pending text is pushed onto the graph according
314       to the character specified.
315
316       Valid markers are: \j for justified, \l for left aligned, \r for right
317       aligned, and \c for centered. In the next section there is an example
318       showing how to use centered formatting.
319
320       \n is a valid alias for \l since incomplete parsing in earlier versions
321       of RRDtool lead to this behavior and a number of people has been using
322       it.
323
324       Normally there are two space characters inserted between every two
325       items printed into the graph. The space following a string can be
326       suppressed by putting a \g at the end of the string. The \g also
327       ignores any space inside the string if it is at the very end of the
328       string. This can be used in connection with %s to suppress empty unit
329       strings.
330
331        GPRINT:a:MAX:%lf%s\g
332
333       A special case is COMMENT:\s which inserts some additional vertical
334       space before placing the next row of legends.
335
336       If you want to have left and right aligned legends on the same line use
337       COMMENT:\u to go one line back like this:
338
339        COMMENT:left\l
340        COMMENT:\u
341        COMMENT:right\r
342
343       There is also a 'nop' control for situations where you want a string to
344       actually end in a backslash character sequence \.
345
346        COMMENT:OS\2\.
347
348       When using a proportional font in your graph, the tab characters or the
349       sequence \t will line-up legend elements. Note that the tabs inserted
350       are relative to the start of the current legend element!
351
352       Since RRDtool 1.3 is using Pango for rending text, you can use Pango
353       markup.  Pango uses the xml span tags for inline formatting
354       instructions.
355
356       A simple example of a marked-up string might be:
357
358        <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
359
360       The complete list of attributes for the span tag (taken from the pango
361       documentation):
362
363       font_desc
364           A font description string, such as "Sans Italic 12"; note that any
365           other span attributes will override this description. So if you
366           have "Sans Italic" and also a style="normal" attribute, you will
367           get Sans normal, not italic.
368
369       font_family
370           A font family name
371
372       face
373           Synonym for font_family
374
375       size
376           Font size in 1024ths of a point, or one of the absolute sizes
377           'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
378           'xx-large', or one of the relative sizes 'smaller' or 'larger'. If
379           you want to specify an absolute size, it's usually easier to take
380           advantage of the ability to specify a partial font description
381           using 'font_desc'; you can use font_desc='12.5' rather than
382           size='12800'.
383
384       style
385           One of 'normal', 'oblique', 'italic'
386
387       weight
388           One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold',
389           'heavy', or a numeric weight
390
391       variant
392           'normal' or 'smallcaps'
393
394       stretch
395           One of 'ultracondensed', 'extracondensed', 'condensed',
396           'semicondensed', 'normal', 'semiexpanded', 'expanded',
397           'extraexpanded', 'ultraexpanded'
398
399       foreground
400           An RGB color specification such as '#00FF00' or a color name such
401           as 'red'
402
403       background
404           An RGB color specification such as '#00FF00' or a color name such
405           as 'red'
406
407       underline
408           One of 'none', 'single', 'double', 'low', 'error'
409
410       underline_color
411           The color of underlines; an RGB color specification such as
412           '#00FF00' or a color name such as 'red'
413
414       rise
415           Vertical displacement, in 10000ths of an em. Can be negative for
416           subscript, positive for superscript.
417
418       strikethrough
419           'true' or 'false' whether to strike through the text
420
421       strikethrough_color
422           The color of crossed out lines; an RGB color specification such as
423           '#00FF00' or a color name such as 'red'
424
425       fallback
426           'true' or 'false' whether to enable fallback. If disabled, then
427           characters will only be used from the closest matching font on the
428           system. No fallback will be done to other fonts on the system that
429           might contain the characters in the text. Fallback is enabled by
430           default. Most applications should not disable fallback.
431
432       lang
433           A language code, indicating the text language
434
435       letter_spacing
436           Inter-letter spacing in 1024ths of a point.
437
438       gravity
439           One of 'south', 'east', 'north', 'west', 'auto'.
440
441       gravity_hint
442           One of 'natural', 'strong', 'line'.
443
444       To save you some typing, there are also some shortcuts:
445
446       b   Bold
447
448       big Makes font relatively larger, equivalent to <span size="larger">
449
450       i   Italic
451
452       s   Strike through
453
454       sub Subscript
455
456       sup Superscript
457
458       small
459           Makes font relatively smaller, equivalent to <span size="smaller">
460
461       tt  Monospace font
462
463       u   Underline
464

SEE ALSO

466       rrdgraph gives an overview of how rrdtool graph works.  rrdgraph_data
467       describes DEF,CDEF and VDEF in detail.  rrdgraph_rpn describes the RPN
468       language used in the ?DEF statements.  rrdgraph_graph page describes
469       all of the graph and print functions.
470
471       Make sure to read rrdgraph_examples for tips&tricks.
472

AUTHOR

474       Program by Tobias Oetiker <tobi@oetiker.ch>
475
476       This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl> with
477       corrections and/or additions by several people
478
479
480
4811.8.0                             2022-03-14                 RRDGRAPH_GRAPH(1)
Impressum