doc/rrdxport.pod

   1 =head1 NAME
   2
   3 rrdxport - Export data in XML format based on data from one or several RRD
   4
   5 =head1 SYNOPSIS
   6
   7 B<rrdtool> B<xport>
   8 S<[B<-s>|B<--start> I<seconds>]>
   9 S<[B<-e>|B<--end> I<seconds>]>
  10 S<[B<-m>|B<--maxrows> I<rows>]>
  11 S<[B<--step> I<value>]>
  12 S<[B<--daemon> I<address>]>
  13 S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]>
  14 S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]>
  15 S<[B<XPORT>B<:>I<vname>[B<:>I<legend>]]>
  16
  17 =head1 DESCRIPTION
  18
  19 The B<xport> function's main purpose is to write an XML formatted
  20 representation of the data stored in one or several B<RRD>s. It
  21 can also extract numerical reports.
  22
  23 If no I<XPORT> statements are found, there will be no output.
  24
  25 =over
  26
  27 =item B<-s>|B<--start> I<seconds> (default end-1day)
  28
  29 The time when the exported range should begin. Time in seconds since
  30 epoch (1970-01-01) is required. Negative numbers are relative to the
  31 current time. By default one day worth of data will be printed.
  32 See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
  33 documentation for a detailed explanation on how to specify time.
  34
  35 =item B<-e>|B<--end> I<seconds> (default now)
  36
  37 The time when the exported range should end. Time in seconds since epoch.
  38 See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
  39 documentation for a detailed explanation of ways to specify time.
  40
  41 =item B<-m>|B<--maxrows> I<rows> (default 400 rows)
  42
  43 This works like the B<-w>|B<--width> parameter of I<rrdgraph>.
  44 In fact it is exactly the same, but the parameter was renamed to
  45 describe its purpose in this module. See I<rrdgraph> documentation
  46 for details.
  47
  48 =item B<--step> I<value> (default automatic)
  49
  50 See L<rrdgraph> documentation.
  51
  52 =item B<--daemon> I<address>
  53
  54 Address of the L<rrdcached> daemon. If specified, a C<flush> command is sent
  55 to the server before reading the RRD files. This allows B<rrdtool> to return
  56 fresh data even if the daemon is configured to cache values for a long time. To
  57 specify a UNIX domain socket use the prefix C<unix:>, see example below. Other
  58 addresses are interpreted as normal network addresses, i.E<nbsp>e. IPv4 or IPv6
  59 addresses in most cases.
  60
  61  rrdtool xport --daemon unix:/var/run/rrdcached.sock ...
  62
  63 =item B<--enumds>
  64
  65 The generated xml should contain the data values in enumerated tags.
  66
  67  <v0>val</v0><v1>val</v1>
  68
  69 =item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>
  70
  71 See I<rrdgraph> documentation.
  72
  73 =item B<CDEF:>I<vname>B<=>I<rpn-expression>
  74
  75 See I<rrdgraph> documentation.
  76
  77 =item B<XPORT:>I<vname>B<:>B<:>I<legend>
  78
  79 At least one I<XPORT> statement should be present. The values
  80 referenced by I<vname> are printed. Optionally add a legend.
  81
  82 =back
  83
  84 =head1 Output format
  85
  86 The output is enclosed in an B<xport> element and contains two
  87 blocks. The first block is enclosed by a B<meta> element and
  88 contains some meta data. The second block is enclosed by a
  89 B<data> element and contains the data rows.
  90
  91 Let's assume that the I<xport> command looks like this:
  92
  93   rrdtool xport \
  94           --start now-1h --end now \
  95           DEF:xx=host-inout.lo.rrd:output:AVERAGE \
  96           DEF:yy=host-inout.lo.rrd:input:AVERAGE \
  97           CDEF:aa=xx,yy,+,8,* \
  98           XPORT:xx:"out bytes" \
  99           XPORT:aa:"in and out bits"
 100
 101 The resulting meta data section is (the values will depend on the
 102 RRD characteristics):
 103
 104   <meta>
 105     <start>1020611700</start>
 106     <step>300</step>
 107     <end>1020615600</end>
 108     <rows>14</rows>
 109     <columns>2</columns>
 110     <legend>
 111       <entry>out bytes</entry>
 112       <entry>in and out bits</entry>
 113     </legend>
 114   </meta>
 115
 116 The resulting data section is:
 117
 118   <data>
 119     <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 120     <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 121     <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 122     <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
 123     <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 124     <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 125     <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 126     <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 127     <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 128     <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 129     <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
 130     <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 131     <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 132     <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
 133   </data>
 134
 135
 136 =head1 EXAMPLE 1
 137
 138   rrdtool xport \
 139           DEF:out=if1-inouts.rrd:outoctets:AVERAGE \
 140           XPORT:out:"out bytes"
 141
 142 =head1 EXAMPLE 2
 143
 144   rrdtool xport \
 145           DEF:out1=if1-inouts.rrd:outoctets:AVERAGE \
 146           DEF:out2=if2-inouts.rrd:outoctets:AVERAGE \
 147           CDEF:sum=out1,out2,+ \
 148           XPORT:out1:"if1 out bytes" \
 149           XPORT:out2:"if2 out bytes" \
 150           XPORT:sum:"output sum"
 151
 152 =head1 ENVIRONMENT VARIABLES
 153
 154 The following environment variables may be used to change the behavior of
 155 C<rrdtoolE<nbsp>xport>:
 156
 157 =over 4
 158
 159 =item B<RRDCACHED_ADDRESS>
 160
 161 If this environment variable is set it will have the same effect as specifying
 162 the C<--daemon> option on the command line. If both are present, the command
 163 line argument takes precedence.
 164
 165 =back
 166
 167 =head1 AUTHOR
 168
 169 Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 170