1 =head1 NAME
3 rrdxport - Export data in XML format based on data from one or several RRD
5 =head1 SYNOPSIS
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<--json>]>
13 S<[B<--daemon> I<address>]>
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>]]>
18 =head1 DESCRIPTION
20 The B<xport> function's main purpose is to write an XML formatted
21 representation of the data stored in one or several B<RRD>s. It
22 can also extract numerical reports.
24 If no I<XPORT> statements are found, there will be no output.
26 =over
28 =item B<-s>|B<--start> I<seconds> (default end-1day)
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.
36 =item B<-e>|B<--end> I<seconds> (default now)
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.
42 =item B<-m>|B<--maxrows> I<rows> (default 400 rows)
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.
49 =item B<--step> I<value> (default automatic)
51 See L<rrdgraph> documentation.
53 =item B<--daemon> I<address>
55 Address of the L<rrdcached> daemon. If specified, a C<flush> command is sent
56 to the server before reading the RRD files. This allows B<rrdtool> to return
57 fresh data even if the daemon is configured to cache values for a long time.
58 For a list of accepted formats, see the B<-l> option in the L<rrdcached> manual.
60 rrdtool xport --daemon unix:/var/run/rrdcached.sock ...
62 =item B<--json>
64 produce json formated output (instead of xml)
66 =item B<--enumds>
68 The generated xml should contain the data values in enumerated tags.
70 <v0>val</v0><v1>val</v1>
72 =item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>
74 See I<rrdgraph> documentation.
76 =item B<CDEF:>I<vname>B<=>I<rpn-expression>
78 See I<rrdgraph> documentation.
80 =item B<XPORT:>I<vname>B<:>B<:>I<legend>
82 At least one I<XPORT> statement should be present. The values
83 referenced by I<vname> are printed. Optionally add a legend.
85 =back
87 =head1 Output format
89 The output is enclosed in an B<xport> element and contains two
90 blocks. The first block is enclosed by a B<meta> element and
91 contains some meta data. The second block is enclosed by a
92 B<data> element and contains the data rows.
94 Let's assume that the I<xport> command looks like this:
96 rrdtool xport \
97 --start now-1h --end now \
98 DEF:xx=host-inout.lo.rrd:output:AVERAGE \
99 DEF:yy=host-inout.lo.rrd:input:AVERAGE \
100 CDEF:aa=xx,yy,+,8,* \
101 XPORT:xx:"out bytes" \
102 XPORT:aa:"in and out bits"
104 The resulting meta data section is (the values will depend on the
105 RRD characteristics):
107 <meta>
108 <start>1020611700</start>
109 <step>300</step>
110 <end>1020615600</end>
111 <rows>14</rows>
112 <columns>2</columns>
113 <legend>
114 <entry>out bytes</entry>
115 <entry>in and out bits</entry>
116 </legend>
117 </meta>
119 The resulting data section is:
121 <data>
122 <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
123 <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
124 <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
125 <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
126 <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
127 <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
128 <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
129 <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
130 <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
131 <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
132 <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
133 <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
134 <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
135 <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
136 </data>
139 =head1 EXAMPLE 1
141 rrdtool xport \
142 DEF:out=if1-inouts.rrd:outoctets:AVERAGE \
143 XPORT:out:"out bytes"
145 =head1 EXAMPLE 2
147 rrdtool xport \
148 DEF:out1=if1-inouts.rrd:outoctets:AVERAGE \
149 DEF:out2=if2-inouts.rrd:outoctets:AVERAGE \
150 CDEF:sum=out1,out2,+ \
151 XPORT:out1:"if1 out bytes" \
152 XPORT:out2:"if2 out bytes" \
153 XPORT:sum:"output sum"
155 =head1 ENVIRONMENT VARIABLES
157 The following environment variables may be used to change the behavior of
158 C<rrdtoolE<nbsp>xport>:
160 =over 4
162 =item B<RRDCACHED_ADDRESS>
164 If this environment variable is set it will have the same effect as specifying
165 the C<--daemon> option on the command line. If both are present, the command
166 line argument takes precedence.
168 =back
170 =head1 AUTHOR
172 Tobias Oetiker E<lt>tobi@oetiker.chE<gt>