doc/rrdxport.pod

   1 =head1 NAME
   2
   3 rrdtool xport - Export data in XML format based on data from one or several RRD
   4
   5 =for html <div align="right"><a href="rrdxport.pdf">PDF</a> version.</div>
   6
   7 =head1 SYNOPSIS
   8
   9 B<rrdtool> B<xport>
  10 S<[B<-s>|B<--start> I<seconds>]>
  11 S<[B<-e>|B<--end> I<seconds>]>
  12 S<[B<-m>|B<--maxrows> I<rows>]>
  13 S<[B<--step> I<value>]>
  14 S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]>
  15 S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]>
  16 S<[B<XPORT>B<:>I<vname>[B<:>I<legend>]]>
  17
  18 =head1 DESCRIPTION
  19
  20 The B<xport> functions main purpose is to write XML formatted
  21 representation of the data stored in one or several B<RRD>s. It
  22 can also extract numerical reports.
  23
  24 If no I<XPORT> statements are found, there will be no output.
  25
  26 =over
  27
  28 =item B<-s>|B<--start> I<seconds> (default end-1day)
  29
  30 The time when the exported range should begin. Time in seconds since
  31 epoch (1970-01-01) is required. Negative numbers are relative to the
  32 current time. By default one day worth of data will be printed.
  33 See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
  34 documentation for a detailed explanation on how to specify time.
  35
  36 =item B<-e>|B<--end> I<seconds> (default now)
  37
  38 The time when the exported range should end. Time in seconds since epoch.
  39 See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
  40 documentation for a detailed explanation of ways to specify time.
  41
  42 =item B<-m>|B<--maxrows> I<rows> (default 400 rows)
  43
  44 This works like the B<-w>|B<--width> parameter of I<rrdgraph>.
  45 In fact it is exactly the same, but the parameter was renamed to
  46 describe its purpose in this module. See I<rrdgraph> documentation
  47 for details.
  48
  49 =item B<--step> I<value> (default automatic)
  50
  51 See I<rrdgraph> documentation.
  52
  53 =item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>
  54
  55 See I<rrdgraph> documentation.
  56
  57 =item B<CDEF:>I<vname>B<=>I<rpn-expression>
  58
  59 See I<rrdgraph> documentation.
  60
  61 =item B<XPORT:>I<vname>B<:>B<:>I<legend>
  62
  63 At least one I<XPORT> statement should be present. The values
  64 referenced by I<vname> are printed. Optionally add a legend.
  65
  66 =back
  67
  68 =head1 Output format
  69
  70 The output is enclosed in a B<xport> element and contains two
  71 blocks. The first block is enclosed by a B<meta> element and
  72 contains some meta data. The second block is enclosed by a
  73 B<data> element and contains the data rows.
  74
  75 Let's assume that the I<xport> command looks like this:
  76
  77   rrdtool xport \
  78           --start now-1h --end now \
  79           DEF:xx=host-inout.lo.rrd:output:AVERAGE \
  80           DEF:yy=host-inout.lo.rrd:input:AVERAGE \
  81           CDEF:aa=xx,yy,+,8,* \
  82           XPORT:xx:"out bytes" \
  83           XPORT:aa:"in and out bits"
  84
  85 The resulting meta data section (the values will depend on the
  86 RRD characteristics):
  87
  88   <meta>
  89     <start>1020611700</start>
  90     <step>300</step>
  91     <end>1020615600</end>
  92     <rows>14</rows>
  93     <columns>2</columns>
  94     <legend>
  95       <entry>out bytes</entry>
  96       <entry>in and out bits</entry>
  97     </legend>
  98   </meta>
  99
 100 The resulting data section:
 101
 102   <data>
 103     <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 104     <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 105     <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 106     <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
 107     <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 108     <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 109     <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 110     <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 111     <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 112     <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 113     <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
 114     <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 115     <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 116     <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
 117   </data>
 118
 119
 120 =head1 EXAMPLE 1
 121
 122   rrdtool xport \
 123           DEF:out=if1-inouts.rrd:outoctets:AVERAGE \
 124           XPORT:out:"out bytes"
 125
 126 =head1 EXAMPLE 2
 127
 128   rrdtool xport \
 129           DEF:out1=if1-inouts.rrd:outoctets:AVERAGE \
 130           DEF:out2=if2-inouts.rrd:outoctets:AVERAGE \
 131           CDEF:sum=out1,out2,+ \
 132           XPORT:out1:"if1 out bytes" \
 133           XPORT:out2:"if2 out bytes" \
 134           XPORT:sum:"output sum"
 135
 136
 137 =head1 AUTHOR
 138
 139 Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
 140