← Back to branch summary

~ubuntu-branches/ubuntu/saucy/rrdtool/saucy-proposed

« back to all changes in this revision

Viewing changes to doc/rrdgraph.pod

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2010-07-22 08:07:01 UTC
  • mfrom: (1.2.8 upstream) (3.1.6 sid)
  • Revision ID: james.westby@ubuntu.com-20100722080701-k46mgdfz6euxwqsm
Tags: 1.4.3-1ubuntu1
* Merge from debian unstable, Remaining changes:
  - debian/control: Don't build against ruby1.9 as we don't want
    it in main.
* require libdbi >= 0.8.3 to prevent aborts when using dbi datasources

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/rrdgraph.pod
1
1
=head1 NAME
2
2
 
3
 
rrdgraph - Round Robin Database tool grapher functions
 
3
rrdgraph - Round Robin Database tool graphing functions
4
4
 
5
5
=head1 SYNOPSIS
6
6
 
30
30
it is best to collect them now using the
31
31
B<L<variable definition|rrdgraph_data/VDEF>> statement.
32
32
Currently this makes no difference, but in a future version
33
 
of rrdtool you may want to collect these values before consolidation.
 
33
of RRDtool you may want to collect these values before consolidation.
34
34
 
35
35
The data fetched from the B<RRA> is then B<consolidated> so that
36
 
there is exactly one datapoint per pixel in the graph. If you do
 
36
there is exactly one data point per pixel in the graph. If you do
37
37
not take care yourself, B<RRDtool> will expand the range slightly
38
38
if necessary. Note, in that case the first and/or last pixel may very
39
39
well become unknown!
48
48
When you are done fetching and processing the data, it is time to
49
49
graph it (or print it).  This ends the B<rrdtool graph> sequence.
50
50
 
 
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.
 
54
 
51
55
=head1 OPTIONS
52
56
 
53
57
 
54
 
=head2 B<graphv>
55
 
 
56
 
This alternate version of B<graph> takes the same arguments and performs the
57
 
same function. The I<v> stands for I<verbose>, which describes the output
58
 
returned. B<graphv> will return a lot of information about the graph using
59
 
the same format as rrdtool info (key = value). See the bottom of the document for more information.
60
 
 
61
58
 
62
59
=head2 I<filename>
63
60
 
80
77
L<AT-STYLE TIME SPECIFICATION|rrdfetch> and L<rrdgraph_examples>.
81
78
By default, B<rrdtool graph> calculates the width of one pixel in
82
79
the time domain and tries to get data from an B<RRA> with that
83
 
resolution.  With the B<step> option you can alter this behaviour.
 
80
resolution.  With the B<step> option you can alter this behavior.
84
81
If you want B<rrdtool graph> to get data at a one-hour resolution
85
82
from the B<RRD>, set B<step> to 3'600. Note: a step smaller than
86
83
one pixel will silently be ignored.
93
90
A horizontal string at the top of the graph and/or a vertically
94
91
placed string at the left hand side of the graph.
95
92
 
96
 
=head2 Right Axis
97
 
 
98
 
[B<--right-axis> I<scale>B<:>I<shift>]
99
 
[B<--right-axis-label> I<label>]
100
 
 
101
 
A second axis will be drawn to the right of the graph. It is tied to the
102
 
left axis via the scale and shift parameters. You can also define a label
103
 
for the right axis.
104
 
 
105
 
[B<--right-axis-format> I<format-string>]
106
 
 
107
 
By default the format of the axis lables gets determined automatically. If
108
 
you want todo this your self, use this option with the same %lf arguments
109
 
you know from the PRING and GPRINT commands.
110
93
 
111
94
=head2 Size
112
95
 
134
117
[B<-r>|B<--rigid>]
135
118
 
136
119
By default the graph will be autoscaling so that it will adjust the
137
 
y-axis to the range of the data. You can change this behaviour by
 
120
y-axis to the range of the data. You can change this behavior by
138
121
explicitly setting the limits. The displayed y-axis will then range at
139
122
least from B<lower-limit> to B<upper-limit>. Autoscaling will still
140
123
permit those boundaries to be stretched unless the B<rigid> option is
168
151
 
169
152
[B<-N>|B<--no-gridfit>]
170
153
 
171
 
In order to avoid anti-aliasing blurring effects rrdtool snaps
 
154
In order to avoid anti-aliasing blurring effects RRDtool snaps
172
155
points to device resolution pixels, this results in a crisper
173
156
appearance. If this is not to your liking, you can use this switch
174
 
to turn this behaviour off.
175
 
 
176
 
Gridfitting is turned off for PDF, EPS, SVG output by default.
177
 
 
178
 
=head2 Grid
179
 
 
180
 
=over
181
 
 
182
 
=item X-Axis
 
157
to turn this behavior off.
 
158
 
 
159
Grid-fitting is turned off for PDF, EPS, SVG output by default.
 
160
 
 
161
=head2 X-Axis
183
162
 
184
163
[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>]
185
164
 
186
165
[B<-x>|B<--x-grid> B<none>]
187
166
 
188
167
The x-axis label is quite complex to configure. If you don't have
189
 
very special needs it is probably best to rely on the autoconfiguration
 
168
very special needs it is probably best to rely on the auto configuration
190
169
to get this right. You can specify the string C<none> to suppress the grid
191
170
and labels altogether.
192
171
 
214
193
each day. The labels are placed exactly between two major grid lines
215
194
as they specify the complete day and not just midnight.
216
195
 
217
 
=item Y-Axis
 
196
=head2 Y-Axis
218
197
 
219
198
[B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>]
220
199
 
255
234
of 0 to prevent any scaling of the y-axis values.
256
235
 
257
236
This option is very effective at confusing the heck out of the default
258
 
rrdtool autoscaler and grid painter. If rrdtool detects that it is not
 
237
RRDtool autoscaling function and grid painter. If RRDtool detects that it is not
259
238
successful in labeling the graph under the given circumstances, it will switch
260
239
to the more robust B<--alt-y-grid> mode.
261
240
 
262
241
[B<-L>|B<--units-length> I<value>]
263
242
 
264
 
How many digits should rrdtool assume the y-axis labels to be? You
 
243
How many digits should RRDtool assume the y-axis labels to be? You
265
244
may have to use this option to make enough space once you start
266
 
fideling with the y-axis labeling.
 
245
fiddling with the y-axis labeling.
267
246
 
268
247
[B<--units=si>]
269
248
 
271
250
the appropriate units (k, M, etc.) instead of using exponential notation.
272
251
Note that for linear graphs, SI notation is used by default.
273
252
 
274
 
=back
 
253
=head2 Right Y Axis
 
254
 
 
255
[B<--right-axis> I<scale>B<:>I<shift>]
 
256
[B<--right-axis-label> I<label>]
 
257
 
 
258
A second axis will be drawn to the right of the graph. It is tied to the
 
259
left axis via the scale and shift parameters. You can also define a label
 
260
for the right axis.
 
261
 
 
262
[B<--right-axis-format> I<format-string>]
 
263
 
 
264
By default the format of the axis labels gets determined automatically. If
 
265
you want to do this your self, use this option with the same %lf arguments
 
266
you know from the PRING and GPRINT commands.
 
267
 
 
268
=head2 Legend
 
269
 
 
270
[B<-g>|B<--no-legend>]
 
271
 
 
272
Suppress generation of the legend; only render the graph.
 
273
 
 
274
[B<-F>|B<--force-rules-legend>]
 
275
 
 
276
Force the generation of HRULE and VRULE legends even if those HRULE or
 
277
VRULE will not be drawn because out of graph boundaries (mimics
 
278
behavior of pre 1.0.42 versions).
 
279
 
 
280
[B<--legend-position>=(north|south|west|east)]
 
281
 
 
282
Place the legend at the given side of the graph. The default is south.
 
283
In west or east position it is necessary to add line breaks manually.
 
284
 
 
285
[B<--legend-direction>=(topdown|bottomup)]
 
286
 
 
287
Place the legend items in the given vertical order. The default is topdown.
 
288
Using bottomup the legend items appear in the same vertical order as a
 
289
stack of lines or areas.
275
290
 
276
291
=head2 Miscellaneous
277
292
 
279
294
 
280
295
Only generate the graph if the current graph is out of date or not existent.
281
296
Note, that all the calculations will happen regardless so that the output of
282
 
PRINT and graphv will be complete regardless. Note that the behaviour of
 
297
PRINT and graphv will be complete regardless. Note that the behavior of
283
298
lazy in this regard has seen several changes over time. The only thing you
284
 
can realy rely on before rrdtool 1.3.7 is that lazy will not generate the
 
299
can really rely on before RRDtool 1.3.7 is that lazy will not generate the
285
300
graph when it is already there and up to date, and also that it will output
286
 
the size of the graph.
287
 
 
 
301
the size of the graph. 
 
302
 
 
303
[B<--daemon> I<address>]
 
304
 
 
305
Address of the L<rrdcached> daemon. If specified, a C<flush> command is sent
 
306
to the server before reading the RRD files. This allows the graph to contain
 
307
fresh data even if the daemon is configured to cache values for a long time.
 
308
For a list of accepted formats, see the B<-l> option in the L<rrdcached> manual.
 
309
 
 
310
 rrdtool graph [...] --daemon unix:/var/run/rrdcached.sock [...]
288
311
 
289
312
[B<-f>|B<--imginfo> I<printfstr>]
290
313
 
313
336
 
314
337
A green arrow is made by: C<--color ARROW#00FF00>
315
338
 
316
 
[B<--zoom> I<factor>]
 
339
[B<--grid-dash> I<on>B<:>I<off>]
 
340
 
 
341
by default the grid is drawn in a 1 on, 1 off pattern. With this option you can set this yourself
 
342
 
 
343
 --grid-dash 1:3    for a dot grid
 
344
 
 
345
 --grid-dash 1:0    for uninterrupted grid lines
 
346
 
 
347
[B<--border> I<width>]]
 
348
 
 
349
Width in pixels for the 3d border drawn around the image. Default 2, 0
 
350
disables the border. See C<SHADEA> and C<SHADEB> above for setting the border
 
351
color.
 
352
 
 
353
[B<--dynamic-labels>]
 
354
 
 
355
Pick the shape of the color marker next to the label according to the element drawn on the graph.
 
356
 
 
357
[B<-m>|B<--zoom> I<factor>]
317
358
 
318
359
Zoom the graphics by the given amount. The factor must be E<gt> 0
319
360
 
327
368
 
328
369
Use Times for the title: C<--font TITLE:13:Times>
329
370
 
 
371
Note that you need to quote the argument to B<--font> if the font-name
 
372
contains whitespace:
 
373
--font "TITLE:13:Some Font"
 
374
 
330
375
If you do not give a font string you can modify just the size of the default font:
331
376
C<--font TITLE:13:>.
332
377
 
352
397
 
353
398
There are 3 font render modes:
354
399
 
355
 
B<normal>: Full Hinting and Antialiasing (default)
356
 
 
357
 
B<light>: Slight Hinting and Antialiasing
358
 
 
359
 
B<mono>: Full Hinting and NO Antialiasing
 
400
B<normal>: Full Hinting and Anti-aliasing (default)
 
401
 
 
402
B<light>: Slight Hinting and Anti-aliasing
 
403
 
 
404
B<mono>: Full Hinting and NO Anti-aliasing
360
405
 
361
406
 
362
407
[B<-B>|B<--font-smoothing-threshold> I<size>]
369
414
 
370
415
[B<-P>|B<--pango-markup>]
371
416
 
372
 
All text in rrdtool is rendered using Pango. With the B<--pango-markup> option, all
 
417
All text in RRDtool is rendered using Pango. With the B<--pango-markup> option, all
373
418
text will be processed by pango markup. This allows to embed some simple html
374
419
like markup tags using 
375
420
 
393
438
 
394
439
There are 2 render modes:
395
440
 
396
 
B<normal>: Graphs are fully Antialiased (default)
 
441
B<normal>: Graphs are fully Anti-aliased (default)
397
442
 
398
 
B<mono>: No Antialiasing
 
443
B<mono>: No Anti-aliasing
399
444
 
400
445
[B<-E>|B<--slope-mode>]
401
446
 
417
462
 
418
463
If images are interlaced they become visible on browsers more quickly.
419
464
 
420
 
[B<-g>|B<--no-legend>]
421
 
 
422
 
Suppress generation of the legend; only render the graph.
423
 
 
424
 
[B<-F>|B<--force-rules-legend>]
425
 
 
426
 
Force the generation of HRULE and VRULE legends even if those HRULE or
427
 
VRULE will not be drawn because out of graph boundaries (mimics
428
 
behaviour of pre 1.0.42 versions).
429
 
 
430
465
[B<-T>|B<--tabwidth> I<value>]
431
466
 
432
467
By default the tab-width is 40 pixels, use this option to change it.
462
497
 
463
498
=head2 graphv
464
499
 
465
 
Calling rrdtool with the graphv option will return information in the
466
 
rrdtool info format. On the command line this means that all output will be
 
500
Calling RRDtool with the graphv option will return information in the
 
501
RRDtool info format. On the command line this means that all output will be
467
502
in key=value format. When used from the Perl and Ruby bindings a hash
468
503
pointer will be returned from the call.
469
504
 
490
525
Especially the 'graph_*' keys are new. They help applications that want to
491
526
know what is where on the graph.
492
527
 
 
528
=head1 ENVIRONMENT VARIABLES
 
529
 
 
530
The following environment variables may be used to change the behavior of
 
531
C<rrdtoolE<nbsp>graph>:
 
532
 
 
533
=over 4
 
534
 
 
535
=item B<RRDCACHED_ADDRESS>
 
536
 
 
537
If this environment variable is set it will have the same effect as specifying
 
538
the C<--daemon> option on the command line. If both are present, the command
 
539
line argument takes precedence.
 
540
 
 
541
=back
 
542
 
493
543
=head1 SEE ALSO
494
544
 
495
545
L<rrdgraph> gives an overview of how B<rrdtool graph> works.