[rrd-developers] it was steve not dave (was: Optional change in graph behavior:--full-size-mode patch)

Tue May 29 21:45:52 CEST 2007

 > steve (rader at ginseng.hep.wisc.edu) who wrote that proposal ...

Enclosed find the .pod and an example.

Or at http://www.hep.wisc.edu/~rader/rrdpiechart/

Comments etc welcome of course.

Discussing it here might be nice?  I'll wait a few days before
I post it on the wiki.

steve
- - -

-------------- next part --------------
=head1 NAME

rrdpiechart - Generate piecharts and tachometer-looking gauges

=head1 SYNOPSIS

B<rrdtool piechart> I<filename>
[I<L<option|rrdgraph/OPTIONS>> ...]
[I<L<data definition|rrdgraph_data/DEF>> ...]
[I<L<data calculation|rrdgraph_data/CDEF>> ...]
[I<L<piechart_element element|rrdpiechart_piechart/ELEMENT>> ...]

=head1 DESCRIPTION

The B<piechart> function can be used to create piecharts and
tachometer-looking gauges that represent B<RRDtool> data from specific
points in time.

=head1 OVERVIEW

The B<L<data definition|rrdgraph_data/DEF>> statements define what
data to use.  The B<L<data calculation|rrdgraph_data/CDEF>>
statements allow you to perform calculations on the
data, which in turn creates new data.  And lastly, the
B<L<piechart_element|rrdpiechart_piechart/ELEMENT>> statements indicate
how the resulting data should be rendered, either as pie B<SLICES>
or as tachometer-looking gauge B<NEEDLES>.

=head1 OPTIONS

=over 4

=item Filename

The name and path of the image file to generate.  The I<filename>
can be 'C<->' to send the image to C<stdout>. In this case,
no other output is generated.

=item Time 

[B<--at> I<time>]

The point in time to display.  Default is "now".  May be be specified
in several formats, see L<AT-STYLE TIME SPECIFICATION|rrdfetch/>.

=item Layout

[B<--width> I<pixels>]
[B<--height> I<pixels>]

The width and height of the I<canvas> (the part of the graph with
the actual piechart).  The default is 200 pixels by 200 pixels.

[B<--outer-radius> I<pixels>] 

The radius of the I<outer circle> drawn.  The default is 90 pixels.

[B<--inner-radius> I<pixels>] 

The radius of the I<inner circle> drawn.  The default is 0 pixels
(solid circle.)

[B<--start-canvas> I<degrees>] 

Specifies the I<angle> where a tachometer-like gauge begins.
The default is zero degrees (piechart).

[B<--end-canvas> I<degrees>] 

Specifies the I<angle> where a tachometer-like gauge ends.
The default is 360 degrees (piechart).

[B<--start-range> I<degrees>] 

Specifies the I<angle> on the piechart where the value zero or
--start-value is rendered.  The default is zero degrees.

[B<--end-range> I<degrees>] 

Specifies the I<angle> on the piechart where 100% of the sum of SLICES
or --end-value is rendered.  The default is 360 degrees.

[B<--start-value> I<value>] 

Specifies the I<value> on the piechart which is rendered at
--start-degrees.

[B<--end-value> I<value>] 

Specifies the I<value> on the piechart which is rendered at
--send-degrees.

[B<--label-slices>]

Draw labels inside slices as per their I<legend>.

[B<--hash-marks> I<value>]

Draw hash marks every I<value> degrees inside the I<outer circle>.

[B<--label-hash-marks> I<value>]

Draw hash marks every I<value> degrees inside the I<outer circle>
and label them.

[B<--label-hash-marks-outside> I<value>]

Draw hash marks every I<value> degrees inside the I<outer circle>
and label them outside the I<outer circle>.

[B<--needle-dial> I<radius>]

Attach needle(s) to an inner-dial (black circle) with the specified
I<radius>.

=item Miscellaneous

[--title> I<string>]

A horizontal string at the top of the graph.

[B<-z>|B<--lazy>]

Only generate the graph if the current graph is out of date or not
existent.

[B<-f>|B<--imginfo> I<printfstr>]

After the image has been created, the graph function uses printf
together with this format string to create output similar to the PRINT
function, only that the printf function is supplied with the parameters
I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
suitable for including the graph into a web page, the command line
would look like this:

 --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'

[B<-c>|B<--color> I<COLORTAG>#I<rrggbb>[I<aa>]]

Override the default colors for the standard elements of the graph. The
I<COLORTAG> is either C<BACK> for the background or C<CANVAS> for the 
background of the actual piechart.

[B<-n>|B<--font> I<FONTTAG>B<:>I<size>B<:>[I<font>]]

This lets you customize which font to use for the various text
elements.  C<DEFAULT> sets the default value for all elements,
C<TITLE> for the title, C<LABEL> for the piechart labels, C<LEGEND>
for the graph legend.  See the rrdgraph documentation for more information.

[B<-a>|B<--imgformat> B<PNG>|B<SVG>|B<EPS>|B<PDF>]

Image format for the generated graph. For the vector formats you can
choose among the standard Postscript fonts Courier-Bold,
Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold,
Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats.

[B<-g>|B<--no-legend>]

Suppress generation of the legend; only render the graph.

[B<-T>|B<--tabwidth> I<value>]

By default the tab-width is 40 pixels, use this option to change it.

[B<-b>|B<--base> I<value>]

If you are graphing memory (not network traffic) this switch
should be set to 1024 so that one KB is 1024 byte.  (For traffic
measurement, 1 Kb/s equals 1000 B/s.)

[B<-W>|B<--watermark> I<string>]

Adds the given string as a watermark, horizontally cantered, at the bottom 
of the graph.

=head1 DATA AND VARIABLES

B<DEF:>I<vname>B<=>I<rrdfile>B<:>I<ds-name>B<:>I<CF>

B<CDEF:>I<vname>B<=>I<RPN expression>

B<VDEF:>I<vname>B<=>I<RPN expression>

You need at least one B<DEF> statement to generate anything. The
other statements are useful but optional.
See L<rrdgraph_data> and L<rrdgraph_rpn> for the exact format.

=head1 ELEMENTS

B<SLICE>B<:>I<value>[B<#>I<color>][B<:>[I<legend>]

B<NEEDLE_A>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>] 

B<NEEDLE_B>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>] 

The B<SLICE> element draws a pie slice sized relative to the sum of
all SLICEs.  The B<NEEDLE_A> element draws a needle that is B<width>
pixels wide with an arrow-head.  The B<NEEDLE_B> element draws a
trangular needle that has a base B<width> pixels wide.

=back

=head1 EXAMPLES

Here is an example which will create a simple piechart:  

  rrdtool piechart example.png \
    --width 400 --height 400 \
    --title "Localhost:/data Disk Utilization" \
    --base 1024 \
    --label-slices \
    DEF:used=localhost-df-data.rrd:df_used:LAST \
    DEF:free=localhost-df-data.rrd:df_free:LAST \
    CDEF:total=used,free,+ \
    SLICE:used#00ff00:"used     " \
    SLICE:free#ffffff:"available" \
    GPRINT:total:LAST:"%8.2lf %sB\c" \
    GPRINT:used:LAST:"%8.2lf %sB\c" \
    GPRINT:free:LAST:"%8.2lf %sB\c"

Assuming you have a 6 TB /data partition that has 4 TB used, the
above example will draw a 400 by 400 pixel piechart with 1) the title
"Localhost:/data Disk Utilization" at the top, 2) a green slice labeled
"used" starting at 12 o'clock that's 240 degrees (4/6*360), 3) a white
(invisible) slice labeled "available" that's 120 degress (2/6*360)
wide, and 4) a legend with total, used and available at the bottom.

Here is an example which creates a fairly complex tachometer-like
gauge:

  rrdtool gauge example.png \
    --radius 80 --inner-radius 20 \
    --start-canvas 240 --end-canvas 120  \
    --start-value 0 --end-value 100 \
    --hash-marks 14 --label-hash-marks 24 \
    --needle-dial 10 \
    DEF:cpu_busy=localhost-cpu-busy.rrd:cpu_busy:LAST \
    NEEDLE_B5:cpu_busy#0000ff

Assuming localhost is 25% cpu busy, the above example will draw a
200 pixel by approximately 180 pixel tachometer that 1) extends from
8 o'clock to 4 o'clock, 2) has 19 hash marks--one every 14 degrees,
3) has 10 labeled hash marks--one every 24 degrees 4) has a blue
triangular needle pointing at 10 o'clock (240+((360-240)+(120)*.25)
attached at the origin to a "needle dial" (black circle) that has
a 10 pixel radius.

=head1 AUTHOR

Program by Tobias Oetiker E<lt>tobi at oetiker.chE<gt>

This manual page was written by Steve Rader E<lt>rader at hep.wisc.edu>E<gt>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/postscript
Size: 7228 bytes
Desc: rrdpiechart.ps
Url : http://lists.oetiker.ch/pipermail/rrd-developers/attachments/20070529/9421b3a9/attachment.ps 