]>
Commit | Line | Data |
---|---|---|
0256acf5 TO |
1 | =head1 NAME |
2 | ||
102be3d7 | 3 | rrdgraph - Round Robin Database tool graphing functions |
0256acf5 | 4 | |
3d72debc | 5 | =head1 SYNOPSIS |
8368d6dc | 6 | |
2085cdd9 | 7 | B<rrdtool graph|graphv> I<filename> |
0256acf5 TO |
8 | [I<L<option|rrdgraph/OPTIONS>> ...] |
9 | [I<L<data definition|rrdgraph_data/DEF>> ...] | |
10 | [I<L<data calculation|rrdgraph_data/CDEF>> ...] | |
11 | [I<L<variable definition|rrdgraph_data/VDEF>> ...] | |
12 | [I<L<graph element|rrdgraph_graph/GRAPH>> ...] | |
13 | [I<L<print element|rrdgraph_graph/PRINT>> ...] | |
8368d6dc TO |
14 | |
15 | =head1 DESCRIPTION | |
16 | ||
be6716b4 | 17 | The B<graph> function of B<RRDtool> is used to present the |
8368d6dc | 18 | data from an B<RRD> to a human viewer. Its main purpose is to |
78664a7b | 19 | create a nice graphical representation, but it can also generate |
8368d6dc TO |
20 | a numerical report. |
21 | ||
22 | =head1 OVERVIEW | |
23 | ||
78664a7b | 24 | B<rrdtool graph> needs data to work with, so you must use one or more |
8368d6dc TO |
25 | B<L<data definition|rrdgraph_data/DEF>> statements to collect this |
26 | data. You are not limited to one database, it's perfectly legal to | |
78664a7b | 27 | collect data from two or more databases (one per statement, though). |
8368d6dc | 28 | |
78664a7b | 29 | If you want to display averages, maxima, percentiles, etcetera |
8368d6dc | 30 | it is best to collect them now using the |
49109cea | 31 | B<L<variable definition|rrdgraph_data/VDEF>> statement. |
78664a7b | 32 | Currently this makes no difference, but in a future version |
102be3d7 | 33 | of RRDtool you may want to collect these values before consolidation. |
8368d6dc TO |
34 | |
35 | The data fetched from the B<RRA> is then B<consolidated> so that | |
102be3d7 | 36 | there is exactly one data point per pixel in the graph. If you do |
8368d6dc | 37 | not take care yourself, B<RRDtool> will expand the range slightly |
78664a7b TO |
38 | if necessary. Note, in that case the first and/or last pixel may very |
39 | well become unknown! | |
40 | ||
41 | Sometimes data is not exactly in the format you would like to display | |
42 | it. For instance, you might be collecting B<bytes> per second, but | |
43 | want to display B<bits> per second. This is what the B<L<data | |
44 | calculation|rrdgraph_data/CDEF>> command is designed for. After | |
45 | B<consolidating> the data, a copy is made and this copy is modified | |
825a5d80 | 46 | using a rather powerful B<L<RPN|rrdgraph_rpn>> command set. |
8368d6dc TO |
47 | |
48 | When you are done fetching and processing the data, it is time to | |
49 | graph it (or print it). This ends the B<rrdtool graph> sequence. | |
50 | ||
547d8c44 TO |
51 | Use B<graphv> instead of B<graph> to get detailed information about the |
52 | graph geometry and data once it is drawn. See the bottom of the document for | |
53 | more information. | |
8368d6dc | 54 | |
547d8c44 | 55 | =head1 OPTIONS |
2085cdd9 | 56 | |
2085cdd9 TO |
57 | |
58 | ||
bfbc9f25 | 59 | =head2 I<filename> |
8368d6dc TO |
60 | |
61 | The name and path of the graph to generate. It is recommended to | |
78664a7b | 62 | end this in C<.png>, C<.svg> or C<.eps>, but B<RRDtool> does not enforce this. |
8368d6dc TO |
63 | |
64 | I<filename> can be 'C<->' to send the image to C<stdout>. In | |
78664a7b | 65 | this case, no other output is generated. |
8368d6dc | 66 | |
bfbc9f25 | 67 | =head2 Time range |
8368d6dc | 68 | |
0cac6f01 TO |
69 | [B<-s>|B<--start> I<time>] |
70 | [B<-e>|B<--end> I<time>] | |
71 | [B<-S>|B<--step> I<seconds>] | |
8368d6dc | 72 | |
78664a7b | 73 | The start and end of the time series you would like to display, and which |
8368d6dc | 74 | B<RRA> the data should come from. Defaults are: 1 day ago until |
e12d9dbc | 75 | now, with the best possible resolution. B<Start> and B<end> can |
8368d6dc | 76 | be specified in several formats, see |
a3061b55 | 77 | L<rrdfetch/"AT-STYLE TIME SPECIFICATION"> and L<rrdgraph_examples>. |
8368d6dc TO |
78 | By default, B<rrdtool graph> calculates the width of one pixel in |
79 | the time domain and tries to get data from an B<RRA> with that | |
102be3d7 | 80 | resolution. With the B<step> option you can alter this behavior. |
8368d6dc | 81 | If you want B<rrdtool graph> to get data at a one-hour resolution |
78664a7b | 82 | from the B<RRD>, set B<step> to 3'600. Note: a step smaller than |
8368d6dc TO |
83 | one pixel will silently be ignored. |
84 | ||
013bc858 PVM |
85 | For non-image B<--imgformat>s see L<rrdxport/"OUTPUT FORMAT"> for details on how |
86 | this affects the output. | |
87 | ||
bfbc9f25 | 88 | =head2 Labels |
8368d6dc | 89 | |
0cac6f01 | 90 | [B<-t>|B<--title> I<string>] |
cd4a7285 | 91 | |
1a0505aa | 92 | A horizontal string placed at the top of the graph which may be |
cd4a7285 MBV |
93 | separated into multiple lines using <br/> or \n |
94 | ||
0cac6f01 | 95 | [B<-v>|B<--vertical-label> I<string>] |
8368d6dc | 96 | |
cd4a7285 | 97 | A vertical string placed at the left hand of the graph. |
8368d6dc | 98 | |
0762f8ee | 99 | |
bfbc9f25 | 100 | =head2 Size |
8368d6dc | 101 | |
0cac6f01 TO |
102 | [B<-w>|B<--width> I<pixels>] |
103 | [B<-h>|B<--height> I<pixels>] | |
104 | [B<-j>|B<--only-graph>] | |
7c58b466 | 105 | [B<-D>|B<--full-size-mode>] |
8368d6dc | 106 | |
7c58b466 | 107 | By default, the width and height of the B<canvas> (the part with |
78664a7b | 108 | the actual data and such). This defaults to 400 pixels by 100 pixels. |
8368d6dc | 109 | |
7c58b466 TO |
110 | If you specify the B<--full-size-mode> option, the width and height |
111 | specify the final dimensions of the output image and the canvas | |
112 | is automatically resized to fit. | |
113 | ||
49109cea | 114 | If you specify the B<--only-graph> option and set the height E<lt> 32 |
78664a7b TO |
115 | pixels you will get a tiny graph image (thumbnail) to use as an icon |
116 | for use in an overview, for example. All labeling will be stripped off | |
117 | the graph. | |
be6716b4 | 118 | |
bfbc9f25 | 119 | =head2 Limits |
8368d6dc | 120 | |
0cac6f01 TO |
121 | [B<-u>|B<--upper-limit> I<value>] |
122 | [B<-l>|B<--lower-limit> I<value>] | |
123 | [B<-r>|B<--rigid>] | |
9b7636a9 | 124 | [B<--allow-shrink>] |
8368d6dc | 125 | |
78664a7b | 126 | By default the graph will be autoscaling so that it will adjust the |
102be3d7 | 127 | y-axis to the range of the data. You can change this behavior by |
78664a7b TO |
128 | explicitly setting the limits. The displayed y-axis will then range at |
129 | least from B<lower-limit> to B<upper-limit>. Autoscaling will still | |
130 | permit those boundaries to be stretched unless the B<rigid> option is | |
544d5d06 | 131 | set. B<allow-shrink> alters behavior of B<rigid> by allowing auto down scale, |
9b7636a9 | 132 | graph will not overrun user specified limits. |
8368d6dc | 133 | |
0cac6f01 | 134 | [B<-A>|B<--alt-autoscale>] |
8368d6dc TO |
135 | |
136 | Sometimes the default algorithm for selecting the y-axis scale is not | |
78664a7b | 137 | satisfactory. Normally the scale is selected from a predefined |
8368d6dc TO |
138 | set of ranges and this fails miserably when you need to graph something |
139 | like C<260 + 0.001 * sin(x)>. This option calculates the minimum and | |
78664a7b | 140 | maximum y-axis from the actual minimum and maximum data values. Our example |
8368d6dc | 141 | would display slightly less than C<260-0.001> to slightly more than |
78664a7b | 142 | C<260+0.001> (this feature was contributed by Sasha Mikheev). |
8368d6dc | 143 | |
8ef971b8 TO |
144 | [B<-J>|B<--alt-autoscale-min>] |
145 | ||
146 | Where C<--alt-autoscale> will modify both the absolute maximum AND minimum | |
147 | values, this option will only affect the minimum value. The maximum | |
148 | value, if not defined on the command line, will be 0. This option can | |
149 | be useful when graphing router traffic when the WAN line uses compression, | |
150 | and thus the throughput may be higher than the WAN line speed. | |
151 | ||
0cac6f01 | 152 | [B<-M>|B<--alt-autoscale-max>] |
8368d6dc TO |
153 | |
154 | Where C<--alt-autoscale> will modify both the absolute maximum AND minimum | |
155 | values, this option will only affect the maximum value. The minimum | |
156 | value, if not defined on the command line, will be 0. This option can | |
157 | be useful when graphing router traffic when the WAN line uses compression, | |
158 | and thus the throughput may be higher than the WAN line speed. | |
159 | ||
0cac6f01 | 160 | [B<-N>|B<--no-gridfit>] |
8b1ffae1 | 161 | |
102be3d7 | 162 | In order to avoid anti-aliasing blurring effects RRDtool snaps |
a33bbffb | 163 | points to device resolution pixels, this results in a crisper |
fce92a6b | 164 | appearance. If this is not to your liking, you can use this switch |
102be3d7 | 165 | to turn this behavior off. |
8368d6dc | 166 | |
102be3d7 | 167 | Grid-fitting is turned off for PDF, EPS, SVG output by default. |
79acd435 | 168 | |
547d8c44 | 169 | =head2 X-Axis |
8368d6dc | 170 | |
0cac6f01 | 171 | [B<-x>|B<--x-grid> I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>B<:>I<LST>B<:>I<LPR>B<:>I<LFM>] |
c028bba0 | 172 | |
0cac6f01 | 173 | [B<-x>|B<--x-grid> B<none>] |
8368d6dc | 174 | |
78664a7b | 175 | The x-axis label is quite complex to configure. If you don't have |
102be3d7 | 176 | very special needs it is probably best to rely on the auto configuration |
78664a7b | 177 | to get this right. You can specify the string C<none> to suppress the grid |
8368d6dc TO |
178 | and labels altogether. |
179 | ||
180 | The grid is defined by specifying a certain amount of time in the I<?TM> | |
181 | positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>, | |
182 | C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should | |
183 | pass between each line or label. This pair (I<?TM:?ST>) needs to be | |
184 | specified for the base grid (I<G??>), the major grid (I<M??>) and the | |
78664a7b | 185 | labels (I<L??>). For the labels you also must define a precision |
8368d6dc TO |
186 | in I<LPR> and a I<strftime> format string in I<LFM>. I<LPR> defines |
187 | where each label will be placed. If it is zero, the label will be | |
188 | placed right under the corresponding line (useful for hours, dates | |
189 | etcetera). If you specify a number of seconds here the label is | |
78664a7b | 190 | centered on this interval (useful for Monday, January etcetera). |
8368d6dc | 191 | |
1ac7dda3 | 192 | --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X |
8368d6dc | 193 | |
78664a7b | 194 | This places grid lines every 10 minutes, major grid lines every hour, |
8368d6dc TO |
195 | and labels every 4 hours. The labels are placed under the major grid |
196 | lines as they specify exactly that time. | |
197 | ||
cdc0d808 | 198 | --x-grid HOUR:8:DAY:1:DAY:1:86400:%A |
8368d6dc TO |
199 | |
200 | This places grid lines every 8 hours, major grid lines and labels | |
201 | each day. The labels are placed exactly between two major grid lines | |
202 | as they specify the complete day and not just midnight. | |
203 | ||
c9b74507 TO |
204 | [B<--week-fmt> I<strftime format string>] |
205 | ||
206 | By default rrdtool uses "Week %V" to render the week number. With this option | |
207 | you can define your own format, without completely overriding the xaxis format. | |
208 | ||
547d8c44 | 209 | =head2 Y-Axis |
8368d6dc | 210 | |
0cac6f01 | 211 | [B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>] |
c028bba0 | 212 | |
0cac6f01 | 213 | [B<-y>|B<--y-grid> B<none>] |
8368d6dc TO |
214 | |
215 | Y-axis grid lines appear at each I<grid step> interval. Labels are | |
216 | placed every I<label factor> lines. You can specify C<-y none> to | |
78664a7b | 217 | suppress the grid and labels altogether. The default for this option is |
8368d6dc TO |
218 | to automatically select sensible values. |
219 | ||
fce92a6b | 220 | If you have set --y-grid to 'none' not only the labels get suppressed, also |
46940a06 TO |
221 | the space reserved for the labels is removed. You can still add space |
222 | manually if you use the --units-length command to explicitly reserve space. | |
223 | ||
f0cc37d1 EB |
224 | [B<--left-axis-formatter> I<formatter-name>] |
225 | ||
c8386f39 | 226 | Specify what formatter to use to render axis values. |
f0cc37d1 EB |
227 | |
228 | =over | |
229 | ||
230 | =item B<numeric> | |
231 | ||
232 | The default, values are expressed as numeric quantities. | |
233 | ||
234 | =item B<timestamp> | |
235 | ||
236 | Values are interpreted as unix timestamps (number of seconds since 1970-01-01 | |
237 | 00:00:00 UTC) and expressed using strftime format (default | |
238 | is '%Y-%m-%d %H:%M:%S'). See also B<--units-length> and B<--left-axis-format>. | |
239 | ||
0ce63f2b EB |
240 | =item B<duration> |
241 | ||
242 | Values are interpreted as duration in milliseconds. Formatting follows the rules | |
243 | of valstrfduration qualified PRINT/GPRINT. See L<rrdgraph_graph>. | |
244 | ||
f0cc37d1 EB |
245 | =back |
246 | ||
795227f2 A |
247 | [B<--left-axis-format> I<format-string>] |
248 | ||
249 | By default the format of the axis labels gets determined automatically. If | |
ba5c9c2d | 250 | you want to do this yourself, use this option with the same %lf arguments |
f0cc37d1 EB |
251 | you know from the PRINT and GPRINT commands, or others if using different |
252 | formatter. | |
795227f2 | 253 | |
0cac6f01 | 254 | [B<-Y>|B<--alt-y-grid>] |
8368d6dc | 255 | |
b5196e2c TO |
256 | Place the Y grid dynamically based on the graph's Y range. The algorithm |
257 | ensures that you always have a grid, that there are enough but not too many | |
258 | grid lines, and that the grid is metric. That is the grid lines are placed | |
259 | every 1, 2, 5 or 10 units. This parameter will also ensure that you get | |
1a0505aa | 260 | enough decimals displayed even if your graph goes from 69.998 to 70.001. |
b5196e2c | 261 | (contributed by Sasha Mikheev). |
8368d6dc | 262 | |
0cac6f01 | 263 | [B<-o>|B<--logarithmic>] |
8368d6dc TO |
264 | |
265 | Logarithmic y-axis scaling. | |
266 | ||
0cac6f01 | 267 | [B<-X>|B<--units-exponent> I<value>] |
8368d6dc | 268 | |
78664a7b TO |
269 | This sets the 10**exponent scaling of the y-axis values. Normally, |
270 | values will be scaled to the appropriate units (k, M, etc.). However, | |
8368d6dc | 271 | you may wish to display units always in k (Kilo, 10e3) even if the data |
78664a7b TO |
272 | is in the M (Mega, 10e6) range, for instance. Value should be an |
273 | integer which is a multiple of 3 between -18 and 18 inclusively. It is | |
274 | the exponent on the units you wish to use. For example, use 3 to | |
8368d6dc TO |
275 | display the y-axis values in k (Kilo, 10e3, thousands), use -6 to |
276 | display the y-axis values in u (Micro, 10e-6, millionths). Use a value | |
277 | of 0 to prevent any scaling of the y-axis values. | |
278 | ||
2047568d | 279 | This option is very effective at confusing the heck out of the default |
102be3d7 | 280 | RRDtool autoscaling function and grid painter. If RRDtool detects that it is not |
2047568d TO |
281 | successful in labeling the graph under the given circumstances, it will switch |
282 | to the more robust B<--alt-y-grid> mode. | |
283 | ||
0cac6f01 | 284 | [B<-L>|B<--units-length> I<value>] |
2047568d | 285 | |
102be3d7 | 286 | How many digits should RRDtool assume the y-axis labels to be? You |
78664a7b | 287 | may have to use this option to make enough space once you start |
c2f7bec9 | 288 | fiddling with the y-axis labeling. |
2047568d | 289 | |
ebcdde13 TO |
290 | [B<--units=si>] |
291 | ||
1a0505aa | 292 | With this option y-axis values on logarithmic graphs will be scaled to |
ebcdde13 TO |
293 | the appropriate units (k, M, etc.) instead of using exponential notation. |
294 | Note that for linear graphs, SI notation is used by default. | |
295 | ||
547d8c44 TO |
296 | =head2 Right Y Axis |
297 | ||
298 | [B<--right-axis> I<scale>B<:>I<shift>] | |
299 | [B<--right-axis-label> I<label>] | |
300 | ||
301 | A second axis will be drawn to the right of the graph. It is tied to the | |
302 | left axis via the scale and shift parameters. You can also define a label | |
303 | for the right axis. | |
304 | ||
f0cc37d1 EB |
305 | [B<--right-axis-formatter> I<formatter-name>] |
306 | ||
c8386f39 | 307 | Specify what formatter to use to render axis values. |
f0cc37d1 EB |
308 | |
309 | =over | |
310 | ||
311 | =item B<numeric> | |
312 | ||
313 | The default, values are expressed as numeric quantities. | |
314 | ||
315 | =item B<timestamp> | |
316 | ||
317 | Values are interpreted as unix timestamps (number of seconds since 1970-01-01 | |
318 | 00:00:00 UTC) and expressed using strftime format (default | |
319 | is '%Y-%m-%d %H:%M:%S'). See also B<--units-length> and B<--right-axis-format>. | |
320 | ||
0ce63f2b EB |
321 | =item B<duration> |
322 | ||
323 | Values are interpreted as duration in milliseconds. Formatting follows the rules | |
324 | of valstrfduration qualified PRINT/GPRINT. See L<rrdgraph_graph>. | |
325 | ||
f0cc37d1 EB |
326 | =back |
327 | ||
328 | ||
547d8c44 TO |
329 | [B<--right-axis-format> I<format-string>] |
330 | ||
102be3d7 | 331 | By default the format of the axis labels gets determined automatically. If |
ba5c9c2d | 332 | you want to do this yourself, use this option with the same %lf arguments |
f0cc37d1 EB |
333 | you know from the PRINT and GPRINT commands, or others if using different |
334 | formatter. | |
8368d6dc | 335 | |
c33ff931 TO |
336 | =head2 Legend |
337 | ||
338 | [B<-g>|B<--no-legend>] | |
339 | ||
340 | Suppress generation of the legend; only render the graph. | |
341 | ||
342 | [B<-F>|B<--force-rules-legend>] | |
343 | ||
344 | Force the generation of HRULE and VRULE legends even if those HRULE or | |
345 | VRULE will not be drawn because out of graph boundaries (mimics | |
102be3d7 | 346 | behavior of pre 1.0.42 versions). |
c33ff931 TO |
347 | |
348 | [B<--legend-position>=(north|south|west|east)] | |
349 | ||
350 | Place the legend at the given side of the graph. The default is south. | |
351 | In west or east position it is necessary to add line breaks manually. | |
352 | ||
8ca2e90b | 353 | [B<--legend-direction>=(topdown|bottomup|bottomup2)] |
c33ff931 TO |
354 | |
355 | Place the legend items in the given vertical order. The default is topdown. | |
356 | Using bottomup the legend items appear in the same vertical order as a | |
8ca2e90b CB |
357 | stack of lines or areas. Using bottomup2 will keep leading and trailing |
358 | COMMENT lines in order, this might be useful for generators that use them | |
359 | for table headers and the like. | |
c33ff931 | 360 | |
bfbc9f25 | 361 | =head2 Miscellaneous |
8368d6dc | 362 | |
0cac6f01 | 363 | [B<-z>|B<--lazy>] |
8368d6dc | 364 | |
3bb911c3 | 365 | Only generate the graph if the current graph is out of date or not existent. |
fbcc0e0c | 366 | Note, that all the calculations will happen regardless so that the output of |
102be3d7 | 367 | PRINT and graphv will be complete regardless. Note that the behavior of |
fbcc0e0c | 368 | lazy in this regard has seen several changes over time. The only thing you |
102be3d7 | 369 | can really rely on before RRDtool 1.3.7 is that lazy will not generate the |
fbcc0e0c | 370 | graph when it is already there and up to date, and also that it will output |
1a0505aa | 371 | the size of the graph. |
8368d6dc | 372 | |
b88bdfc6 | 373 | [B<-d>|B<--daemon> I<address>] |
c2f7bec9 TO |
374 | |
375 | Address of the L<rrdcached> daemon. If specified, a C<flush> command is sent | |
376 | to the server before reading the RRD files. This allows the graph to contain | |
a548a57d TO |
377 | fresh data even if the daemon is configured to cache values for a long time. |
378 | For a list of accepted formats, see the B<-l> option in the L<rrdcached> manual. | |
c2f7bec9 TO |
379 | |
380 | rrdtool graph [...] --daemon unix:/var/run/rrdcached.sock [...] | |
381 | ||
0cac6f01 | 382 | [B<-f>|B<--imginfo> I<printfstr>] |
8368d6dc TO |
383 | |
384 | After the image has been created, the graph function uses printf | |
385 | together with this format string to create output similar to the PRINT | |
78664a7b | 386 | function, only that the printf function is supplied with the parameters |
8368d6dc TO |
387 | I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag |
388 | suitable for including the graph into a web page, the command line | |
389 | would look like this: | |
390 | ||
0cac6f01 | 391 | --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">' |
8368d6dc | 392 | |
0cac6f01 | 393 | [B<-c>|B<--color> I<COLORTAG>#I<rrggbb>[I<aa>]] |
8368d6dc | 394 | |
ab02aae1 TO |
395 | Override the default colors for the standard elements of the graph. The |
396 | I<COLORTAG> is one of C<BACK> background, C<CANVAS> for the background of | |
397 | the actual graph, C<SHADEA> for the left and top border, C<SHADEB> for the | |
398 | right and bottom border, C<GRID>, C<MGRID> for the major grid, C<FONT> for | |
102863ea | 399 | the color of the font, C<AXIS> for the axis of the graph, C<FRAME> for the |
f04f4d23 | 400 | line around the color spots, and finally C<ARROW> for the arrow head pointing |
102863ea TO |
401 | up and forward. Each color is composed out of three hexadecimal numbers |
402 | specifying its rgb color component (00 is off, FF is maximum) of red, green | |
403 | and blue. Optionally you may add another hexadecimal number specifying the | |
404 | transparency (FF is solid). You may set this option several times to alter | |
405 | multiple defaults. | |
8368d6dc | 406 | |
a4feb80c | 407 | A green arrow is made by: C<--color ARROW#00FF00> |
8368d6dc | 408 | |
26b84b4b TO |
409 | [B<--grid-dash> I<on>B<:>I<off>] |
410 | ||
411 | by default the grid is drawn in a 1 on, 1 off pattern. With this option you can set this yourself | |
412 | ||
413 | --grid-dash 1:3 for a dot grid | |
1a0505aa | 414 | |
26b84b4b TO |
415 | --grid-dash 1:0 for uninterrupted grid lines |
416 | ||
1ebcaf87 | 417 | [B<--border> I<width>] |
7981a9d9 TO |
418 | |
419 | Width in pixels for the 3d border drawn around the image. Default 2, 0 | |
420 | disables the border. See C<SHADEA> and C<SHADEB> above for setting the border | |
421 | color. | |
422 | ||
f3878554 TO |
423 | [B<--dynamic-labels>] |
424 | ||
425 | Pick the shape of the color marker next to the label according to the element drawn on the graph. | |
426 | ||
056375bb | 427 | [B<-m>|B<--zoom> I<factor>] |
cdab6835 | 428 | |
78664a7b | 429 | Zoom the graphics by the given amount. The factor must be E<gt> 0 |
cdab6835 | 430 | |
aee7edcd | 431 | [B<-n>|B<--font> I<FONTTAG>B<:>I<size>[B<:>I<font>]] |
cdab6835 | 432 | |
f04f4d23 TO |
433 | This lets you customize which font to use for the various text elements on |
434 | the RRD graphs. C<DEFAULT> sets the default value for all elements, C<TITLE> | |
435 | for the title, C<AXIS> for the axis labels, C<UNIT> for the vertical unit | |
436 | label, C<LEGEND> for the graph legend, C<WATERMARK> for the watermark on the | |
437 | edge of the graph. | |
cdab6835 | 438 | |
5b5ecbc2 | 439 | Use Times for the title: C<--font TITLE:13:Times> |
cdab6835 | 440 | |
e2560d73 TO |
441 | Note that you need to quote the argument to B<--font> if the font-name |
442 | contains whitespace: | |
443 | --font "TITLE:13:Some Font" | |
444 | ||
fce92a6b | 445 | If you do not give a font string you can modify just the size of the default font: |
3e42948a TO |
446 | C<--font TITLE:13:>. |
447 | ||
448 | If you specify the size 0 then you can modify just the font without touching | |
fce92a6b | 449 | the size. This is especially useful for altering the default font without |
5b5ecbc2 | 450 | resetting the default fontsizes: C<--font DEFAULT:0:Courier>. |
3e42948a | 451 | |
22264ce8 TO |
452 | RRDtool comes with a preset default font. You can set the environment |
453 | variable C<RRD_DEFAULT_FONT> if you want to change this. | |
454 | ||
5b5ecbc2 TO |
455 | RRDtool uses Pango for its font handling. This means you can to use |
456 | the full Pango syntax when selecting your font: | |
457 | ||
458 | The font name has the form "[I<FAMILY-LIST>] [I<STYLE-OPTIONS>] [I<SIZE>]", | |
459 | where I<FAMILY-LIST> is a comma separated list of families optionally | |
460 | terminated by a comma, I<STYLE_OPTIONS> is a whitespace separated list of | |
461 | words where each WORD describes one of style, variant, weight, stretch, or | |
462 | gravity, and I<SIZE> is a decimal number (size in points) or optionally | |
463 | followed by the unit modifier "px" for absolute size. Any one of the options | |
464 | may be absent. | |
0cac6f01 | 465 | |
a33bbffb | 466 | [B<-R>|B<--font-render-mode> {B<normal>,B<light>,B<mono>}] |
e8c5efd3 | 467 | |
a33bbffb TO |
468 | There are 3 font render modes: |
469 | ||
102be3d7 | 470 | B<normal>: Full Hinting and Anti-aliasing (default) |
a33bbffb | 471 | |
102be3d7 | 472 | B<light>: Slight Hinting and Anti-aliasing |
a33bbffb | 473 | |
102be3d7 | 474 | B<mono>: Full Hinting and NO Anti-aliasing |
5b5ecbc2 | 475 | |
e8c5efd3 TO |
476 | |
477 | [B<-B>|B<--font-smoothing-threshold> I<size>] | |
478 | ||
5b5ecbc2 TO |
479 | (this gets ignored in 1.3 for now!) |
480 | ||
e8c5efd3 TO |
481 | This specifies the largest font size which will be rendered |
482 | bitmapped, that is, without any font smoothing. By default, | |
483 | no text is rendered bitmapped. | |
484 | ||
ff1db7ad TO |
485 | [B<-P>|B<--pango-markup>] |
486 | ||
102be3d7 | 487 | All text in RRDtool is rendered using Pango. With the B<--pango-markup> option, all |
71197ffb | 488 | text will be processed by pango markup. This allows one to embed some simple html |
1a0505aa | 489 | like markup tags using |
825a5d80 | 490 | |
ff1db7ad TO |
491 | <span key="value">text</span> |
492 | ||
493 | Apart from the verbose syntax, there are also the following short tags available. | |
494 | ||
495 | b Bold | |
496 | big Makes font relatively larger, equivalent to <span size="larger"> | |
497 | i Italic | |
498 | s Strikethrough | |
499 | sub Subscript | |
500 | sup Superscript | |
501 | small Makes font relatively smaller, equivalent to <span size="smaller"> | |
502 | tt Monospace font | |
1a0505aa | 503 | u Underline |
825a5d80 | 504 | |
0f9a8cee | 505 | More details on L<http://developer.gnome.org/pango/stable/PangoMarkupFormat.html>. |
ff1db7ad | 506 | |
a33bbffb TO |
507 | [B<-G>|B<--graph-render-mode> {B<normal>,B<mono>}] |
508 | ||
509 | There are 2 render modes: | |
510 | ||
102be3d7 | 511 | B<normal>: Graphs are fully Anti-aliased (default) |
a33bbffb | 512 | |
102be3d7 | 513 | B<mono>: No Anti-aliasing |
a33bbffb | 514 | |
077233ce TO |
515 | [B<-E>|B<--slope-mode>] |
516 | ||
517 | RRDtool graphs are composed of stair case curves by default. This is in line with | |
518 | the way RRDtool calculates its data. Some people favor a more 'organic' look | |
519 | for their graphs even though it is not all that true. | |
520 | ||
c954b9a9 | 521 | [B<-a>|B<--imgformat> B<PNG>|B<SVG>|B<EPS>|B<PDF>|B<XML>|B<XMLENUM>|B<JSON>|B<JSONTIME>|B<CSV>|B<TSV>|B<SSV>] |
cdab6835 | 522 | |
78664a7b TO |
523 | Image format for the generated graph. For the vector formats you can |
524 | choose among the standard Postscript fonts Courier-Bold, | |
525 | Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold, | |
526 | Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol, | |
527 | Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats. | |
cdab6835 | 528 | |
1a0505aa | 529 | For Export type you can define |
ba5c9c2d | 530 | XML, XMLENUM (enumerates the value tags <v0>,<v1>,<v2>,...), |
c954b9a9 TO |
531 | JSON, JSONTIME (adds a timestamp to each data row), |
532 | CSV (=comma separated values), TSV (=tab separated values), SSV (=semicolon separated values), | |
dd286795 TO |
533 | (for comma/tab/semicolon separated values the time format by default is in the form of unix time. to change it to something else use: --x-grid MINUTE:10:HOUR:1:HOUR:4:0:"%Y-%m-%d %H:%M:%S") |
534 | ||
013bc858 PVM |
535 | For non-image B<--imgformat>s see L<rrdxport/"OUTPUT FORMAT"> for details on |
536 | the output. | |
537 | ||
0cac6f01 | 538 | [B<-i>|B<--interlaced>] |
8368d6dc | 539 | |
5b5ecbc2 TO |
540 | (this gets ignored in 1.3 for now!) |
541 | ||
6b1453e0 | 542 | If images are interlaced they become visible on browsers more quickly. |
8368d6dc | 543 | |
0cac6f01 | 544 | [B<-T>|B<--tabwidth> I<value>] |
ab02aae1 TO |
545 | |
546 | By default the tab-width is 40 pixels, use this option to change it. | |
547 | ||
0cac6f01 | 548 | [B<-b>|B<--base> I<value>] |
8368d6dc TO |
549 | |
550 | If you are graphing memory (and NOT network traffic) this switch | |
551 | should be set to 1024 so that one Kb is 1024 byte. For traffic | |
552 | measurement, 1 kb/s is 1000 b/s. | |
553 | ||
502f5219 TO |
554 | [B<-W>|B<--watermark> I<string>] |
555 | ||
1a0505aa | 556 | Adds the given string as a watermark, horizontally centered, at the bottom |
502f5219 TO |
557 | of the graph. |
558 | ||
0168e3a2 | 559 | [B<-Z>|B<--use-nan-for-all-missing-data>] |
5687a92b VB |
560 | |
561 | If one DS is missing, either because the RRD is not available or | |
562 | because it does not contain the requested DS name, just assume that we | |
563 | got empty values instead of raising a fatal error. | |
564 | ||
c00bdb67 | 565 | [B<--add-jsontime>] |
566 | ||
567 | Adds B<xport> data in B<JSONTIME> format, giving both graph image data | |
568 | and data point values in one call to graphv command. | |
569 | ||
1d22382a JYA |
570 | [B<--utc>] |
571 | ||
572 | Force the timezone to be UTC. Equivalent to doing TZ=UTC rrdtool graph .... | |
573 | This is useful to calculate daily average ranging from midnight to midnight rather than say the last 24 hours. | |
574 | ||
bfbc9f25 | 575 | =head2 Data and variables |
8368d6dc | 576 | |
0cac6f01 | 577 | B<DEF:>I<vname>B<=>I<rrdfile>B<:>I<ds-name>B<:>I<CF>[B<:step=>I<step>][B<:start=>I<time>][B<:end=>I<time>] |
8368d6dc | 578 | |
0cac6f01 | 579 | B<CDEF:>I<vname>B<=>I<RPN expression> |
8368d6dc | 580 | |
0cac6f01 | 581 | B<VDEF:>I<vname>B<=>I<RPN expression> |
8368d6dc | 582 | |
eb14bf1f TO |
583 | You need at least one B<DEF> and one B<LINE>, B<AREA>, B<GPRINT>, B<PRINT> |
584 | statement to generate anything useful. | |
585 | ||
78664a7b | 586 | See L<rrdgraph_data> and L<rrdgraph_rpn> for the exact format. |
8368d6dc | 587 | |
825a5d80 | 588 | NOTE: B<Graph and print elements> |
8368d6dc TO |
589 | |
590 | You need at least one graph element to generate an image and/or | |
591 | at least one print statement to generate a report. | |
78664a7b | 592 | See L<rrdgraph_graph> for the exact format. |
8368d6dc | 593 | |
2085cdd9 TO |
594 | =head2 graphv |
595 | ||
102be3d7 TO |
596 | Calling RRDtool with the graphv option will return information in the |
597 | RRDtool info format. On the command line this means that all output will be | |
fce92a6b | 598 | in key=value format. When used from the Perl and Ruby bindings a hash |
2085cdd9 TO |
599 | pointer will be returned from the call. |
600 | ||
601 | When the filename '-' is given, the contents of the graph itself will also | |
602 | be returned through this interface (hash key 'image'). On the command line | |
603 | the output will look like this: | |
604 | ||
605 | print[0] = "0.020833" | |
606 | print[1] = "0.0440833" | |
607 | graph_left = 51 | |
608 | graph_top = 22 | |
609 | graph_width = 400 | |
610 | graph_height = 100 | |
77e55973 TO |
611 | graph_start = 1232908800 |
612 | graph_end = 1232914200 | |
2085cdd9 TO |
613 | image_width = 481 |
614 | image_height = 154 | |
615 | value_min = 0.0000000000e+00 | |
616 | value_max = 4.0000000000e-02 | |
617 | image = BLOB_SIZE:8196 | |
618 | [... 8196 bytes of image data ...] | |
619 | ||
620 | There is more information returned than in the standard interface. | |
621 | Especially the 'graph_*' keys are new. They help applications that want to | |
622 | know what is where on the graph. | |
623 | ||
c2f7bec9 TO |
624 | =head1 ENVIRONMENT VARIABLES |
625 | ||
626 | The following environment variables may be used to change the behavior of | |
627 | C<rrdtoolE<nbsp>graph>: | |
628 | ||
629 | =over 4 | |
630 | ||
631 | =item B<RRDCACHED_ADDRESS> | |
632 | ||
633 | If this environment variable is set it will have the same effect as specifying | |
634 | the C<--daemon> option on the command line. If both are present, the command | |
635 | line argument takes precedence. | |
636 | ||
1ebcaf87 | 637 | =item B<RRD_DEFAULT_FONT> |
638 | ||
639 | RRDtool comes with a preset default font. You can set the environment variable | |
640 | RRD_DEFAULT_FONT if you want to change this. | |
641 | ||
c2f7bec9 TO |
642 | =back |
643 | ||
439429d0 TO |
644 | =head1 SEE ALSO |
645 | ||
646 | L<rrdgraph> gives an overview of how B<rrdtool graph> works. | |
78664a7b TO |
647 | L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail. |
648 | L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements. | |
439429d0 TO |
649 | L<rrdgraph_graph> page describes all of the graph and print functions. |
650 | ||
651 | Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks. | |
652 | ||
653 | =head1 AUTHOR | |
654 | ||
5892bcb9 | 655 | Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt> |
439429d0 | 656 | |
75bad8b1 TO |
657 | This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt> |
658 | with corrections and/or additions by several people | |
8368d6dc | 659 |