=head1 NAME

rrdxport - Export data in XML format based on data from one or several RRD

=head1 SYNOPSIS

B<rrdtool> B<xport>
S<[B<-s>|B<--start> I<seconds>]>
S<[B<-e>|B<--end> I<seconds>]>
S<[B<-m>|B<--maxrows> I<rows>]>
S<[B<--step> I<value>]>
S<[B<--json>]>
S<[B<-t>|B<--showtime>]>
S<[B<--enumds>]>
S<[B<--daemon>|B<-d> I<address>]>
S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]>
S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]>
S<[B<XPORT>B<:>I<vname>[B<:>I<legend>]]>

=head1 DESCRIPTION

The B<xport> function's main purpose is to write an XML formatted
representation of the data stored in one or several B<RRD>s. It
can also extract numerical reports.

If no I<XPORT> statements are found, there will be no output.

=over

=item B<-s>|B<--start> I<seconds> (default end-1day)

The time when the exported range should begin. Time in seconds since
epoch (1970-01-01) is required. Negative numbers are relative to the
current time. By default one day worth of data will be printed.
See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
documentation for a detailed explanation on how to specify time.

=item B<-e>|B<--end> I<seconds> (default now)

The time when the exported range should end. Time in seconds since epoch.
See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch>
documentation for a detailed explanation of ways to specify time.

=item B<-m>|B<--maxrows> I<rows> (default 400 rows)

This works like the B<-w>|B<--width> parameter of I<rrdgraph>.
In fact it is exactly the same, but the parameter was renamed to
describe its purpose in this module. See I<rrdgraph> documentation
for details.

=item B<--step> I<value> (default automatic)

See L<rrdgraph> documentation.

=item B<--daemon>|B<-d> I<address>

Address of the L<rrdcached> daemon. If specified, a C<flush> command is sent
to the server before reading the RRD files. This allows B<rrdtool> to return
fresh data even if the daemon is configured to cache values for a long time.
For a list of accepted formats, see the B<-l> option in the L<rrdcached> manual.

  rrdtool xport --daemon unix:/var/run/rrdcached.sock ...

=item B<-t>|B<--showtime>

include the time into each data row.

=item B<--json>

produce json formatted output (instead of xml)

=item B<--enumds>

The generated xml should contain the data values in enumerated tags.

 <v0>val</v0><v1>val</v1>

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

See I<rrdgraph> documentation.

=item B<CDEF:>I<vname>B<=>I<rpn-expression>

See I<rrdgraph> documentation.

=item B<XPORT:>I<vname>[B<:>I<legend>]

At least one I<XPORT> statement should be present. The values
referenced by I<vname> are printed. Optionally add a legend.

=back

=head1 Output format

The output is enclosed in an B<xport> element and contains two
blocks. The first block is enclosed by a B<meta> element and
contains some meta data. The second block is enclosed by a
B<data> element and contains the data rows.

Let's assume that the I<xport> command looks like this:

  rrdtool xport \
          --start now-1h --end now \
          DEF:xx=host-inout.lo.rrd:output:AVERAGE \
	  DEF:yy=host-inout.lo.rrd:input:AVERAGE \
          CDEF:aa=xx,yy,+,8,* \
          XPORT:xx:"out bytes" \
          XPORT:aa:"in and out bits"

The resulting meta data section is (the values will depend on the
RRD characteristics):

  <meta>
    <start>1020611700</start>
    <step>300</step>
    <end>1020615600</end>
    <rows>14</rows>
    <columns>2</columns>
    <legend>
      <entry>out bytes</entry>
      <entry>in and out bits</entry>
    </legend>
  </meta>

The resulting data section is:

  <data>
    <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
    <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
    <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
    <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
  </data>


=head1 EXAMPLE 1

  rrdtool xport \
          DEF:out=if1-inouts.rrd:outoctets:AVERAGE \
          XPORT:out:"out bytes"

=head1 EXAMPLE 2

  rrdtool xport \
          DEF:out1=if1-inouts.rrd:outoctets:AVERAGE \
          DEF:out2=if2-inouts.rrd:outoctets:AVERAGE \
	  CDEF:sum=out1,out2,+ \
          XPORT:out1:"if1 out bytes" \
          XPORT:out2:"if2 out bytes" \
	  XPORT:sum:"output sum"

=head1 ENVIRONMENT VARIABLES

The following environment variables may be used to change the behavior of
C<rrdtoolE<nbsp>xport>:

=over 4

=item B<RRDCACHED_ADDRESS>

If this environment variable is set it will have the same effect as specifying
the C<--daemon> option on the command line. If both are present, the command
line argument takes precedence.

=back

=head1 AUTHOR

Tobias Oetiker E<lt>tobi@oetiker.chE<gt>

