]>
Commit | Line | Data |
---|---|---|
0256acf5 TO |
1 | =head1 NAME |
2 | ||
8c4fa85c | 3 | rrdgraph_data - preparing data for graphing in rrdtool graph |
8368d6dc | 4 | |
3d72debc | 5 | =head1 SYNOPSIS |
8368d6dc | 6 | |
b09c79e8 | 7 | B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>][:daemon=I<E<lt>addressE<gt>>] |
8368d6dc TO |
8 | |
9 | B<VDEF>:I<vname>=I<RPN expression> | |
10 | ||
11 | B<CDEF>:I<vname>=I<RPN expression> | |
12 | ||
13 | =head1 DESCRIPTION | |
14 | ||
8c4fa85c TO |
15 | These three instructions extract data values out of the B<RRD> files, |
16 | optionally altering them (think, for example, of a bytes to bits | |
17 | conversion). If so desired, you can also define variables containing | |
18 | useful information such as maximum, minimum etcetera. Two of the | |
19 | instructions use a language called B<RPN> which is described in its | |
20 | own manual page. | |
8368d6dc | 21 | |
61616b9a | 22 | Variable names (I<vname>) must be made up strings of the following characters |
c72e75a9 | 23 | C<A-Z, a-z, 0-9, _, -> and a maximum length of 255 characters. |
61616b9a | 24 | |
672d4d3c | 25 | When picking variable names, make sure you do not choose a name that is |
8efb08c5 | 26 | already taken by an RPN operator. A safe bet is to use lowercase or |
102be3d7 | 27 | mixed case names for variables since operators will always be in uppercase. |
672d4d3c | 28 | |
8368d6dc TO |
29 | =head1 DEF |
30 | ||
b09c79e8 | 31 | B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>][:reduce=I<E<lt>B<CF>E<gt>>][:daemon=I<E<lt>addressE<gt>>] |
8368d6dc TO |
32 | |
33 | This command fetches data from an B<RRD> file. The virtual name | |
34 | I<vname> can then be used throughout the rest of the script. By | |
35 | default, an B<RRA> which contains the correct consolidated data | |
36 | at an appropriate resolution will be chosen. The resolution can | |
e12d9dbc | 37 | be overridden with the L<--step|rrdgraph/item_Time> option. |
3d72debc | 38 | The resolution can again be overridden by specifying the B<step size>. |
d998b12a AB |
39 | The time span of this data is the same as for the graph by default, |
40 | you can override this by specifying B<start and end>. Remember to | |
41 | escape colons in the time specification! | |
8368d6dc | 42 | |
8c4fa85c TO |
43 | If the resolution of the data is higher than the resolution of the |
44 | graph, the data will be further consolidated. This may result in | |
8368d6dc TO |
45 | a graph that spans slightly more time than requested. |
46 | Ideally each point in the graph should correspond with one B<CDP> | |
47 | from an B<RRA>. For instance, if your B<RRD> has an B<RRA> with | |
48 | a resolution of 1800 seconds per B<CDP>, you should create an | |
49 | image with width 400 and time span 400*1800 seconds (use appropriate | |
50 | start and end times, such as C<--start end-8days8hours>). | |
51 | ||
8db0db54 | 52 | If consolidation needs to be done, the B<CF> of the B<RRA> specified in the |
102be3d7 | 53 | B<DEF> itself will be used to reduce the data density. This behavior can |
8db0db54 TO |
54 | be changed using C<:reduce=I<E<lt>B<CF>E<gt>>>. This optional parameter |
55 | specifies the B<CF> to use during the data reduction phase. | |
56 | ||
b09c79e8 | 57 | It is possible to request single data sources from a specific I<RRDCacheD>, see |
f0981d50 | 58 | L<rrdcached>, using the C<:daemon=I<E<lt>addressE<gt>>> parameter. The |
b09c79e8 | 59 | value given to this parameter follows the same syntax as other means to specify |
f0981d50 PB |
60 | the address of the caching daemon. It is described in detail in |
61 | L<rrdcached>. Beware, however, that colons (in IPv6 addresses | |
b09c79e8 TO |
62 | and as a port separator, for example) need to be escaped using a backslash. |
63 | ||
0b72dad0 | 64 | Example: |
8368d6dc | 65 | |
0b72dad0 AB |
66 | DEF:ds0=router.rrd:ds0:AVERAGE |
67 | DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200 | |
d998b12a AB |
68 | DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h |
69 | DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h | |
b09c79e8 | 70 | DEF:ds0weekly=router.rrd:ds0:AVERAGE:daemon=collect1.example.com |
8368d6dc TO |
71 | |
72 | =head1 VDEF | |
73 | ||
74 | B<VDEF>:I<vname>=I<RPN expression> | |
75 | ||
76 | This command returns a value and/or a time according to the B<RPN> | |
77 | statements used. The resulting I<vname> will, depending on the | |
78 | functions used, have a value and a time component. When you use | |
79 | this I<vname> in another B<RPN> expression, you are effectively | |
80 | inserting its value just as if you had put a number at that place. | |
81 | The variable can also be used in the various graph and print | |
49109cea | 82 | elements. |
8368d6dc TO |
83 | |
84 | Example: C<VDEF:avg=mydata,AVERAGE> | |
85 | ||
fce92a6b | 86 | Note that currently only aggregation functions work in VDEF rpn expressions. |
bc3632fa TO |
87 | Patches to change this are welcome. |
88 | ||
8368d6dc TO |
89 | =head1 CDEF |
90 | ||
91 | B<CDEF>:I<vname>=I<RPN expression> | |
92 | ||
93 | This command creates a new set of data points (in memory only, not | |
94 | in the B<RRD> file) out of one or more other data series. The B<RPN> | |
95 | instructions are used to evaluate a mathematical function on each | |
96 | data point. The resulting I<vname> can then be used further on in | |
97 | the script, just as if it were generated by a B<DEF> instruction. | |
98 | ||
99 | Example: C<CDEF:mydatabits=mydata,8,*> | |
100 | ||
12deebbf TO |
101 | =head1 About CDEF versus VDEF |
102 | ||
103 | At some point in processing, B<RRDtool> has gathered an array of rates | |
104 | ready to display. | |
105 | ||
106 | B<CDEF> works on such an array. For example, I<CDEF:new=ds0,8,*> | |
107 | would multiply each of the array members by eight (probably | |
108 | transforming bytes into bits). The result is an array containing the | |
109 | new values. | |
110 | ||
111 | B<VDEF> also works on such an array but in a different way. For | |
112 | example, I<VDEF:max=ds0,MAXIMUM> would scan each of the array members | |
113 | and store the maximum value. | |
114 | ||
1a0505aa | 115 | =head2 When do you use B<VDEF> versus B<CDEF>? |
12deebbf TO |
116 | |
117 | Use B<CDEF> to transform your data prior to graphing. In the above | |
118 | example, we'd use a B<CDEF> to transform bytes to bits before | |
119 | graphing the bits. | |
120 | ||
121 | You use a B<VDEF> if you want I<max(1,5,3,2,4)> to return five which | |
122 | would be displayed in the graph's legend (to answer, what was the | |
123 | maximum value during the graph period). | |
124 | ||
125 | If you want to apply 'complex' operations to the result of a VDEF you have | |
126 | to use a CDEF again since VDEFs only look like RPN expressions, they aren't | |
102be3d7 | 127 | really. |
12deebbf | 128 | |
439429d0 TO |
129 | =head1 SEE ALSO |
130 | ||
131 | L<rrdgraph> gives an overview of how B<rrdtool graph> works. | |
8c4fa85c TO |
132 | L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail. |
133 | L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements. | |
439429d0 TO |
134 | L<rrdgraph_graph> page describes all of the graph and print functions. |
135 | ||
136 | Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks. | |
137 | ||
138 | =head1 AUTHOR | |
139 | ||
5892bcb9 | 140 | Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt> |
439429d0 | 141 | |
75bad8b1 TO |
142 | This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt> |
143 | with corrections and/or additions by several people |