doc/rrdxport.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <title>rrdxport</title>
   5 <link rev="made" href="mailto:root@localhost" />
   6 </head>
   7
   8 <body style="background-color: white">
   9
  10 <p><a name="__index__"></a></p>
  11 <!-- INDEX BEGIN -->
  12 <!--
  13
  14 <ul>
  15
  16         <li><a href="#name">NAME</a></li>
  17         <li><a href="#synopsis">SYNOPSIS</a></li>
  18         <li><a href="#description">DESCRIPTION</a></li>
  19         <li><a href="#output_format">Output format</a></li>
  20         <li><a href="#example_1">EXAMPLE 1</a></li>
  21         <li><a href="#example_2">EXAMPLE 2</a></li>
  22         <li><a href="#environment_variables">ENVIRONMENT VARIABLES</a></li>
  23         <li><a href="#author">AUTHOR</a></li>
  24 </ul>
  25 -->
  26 <!-- INDEX END -->
  27
  28 <p>
  29 </p>
  30 <h1><a name="name">NAME</a></h1>
  31 <p>rrdxport - Export data in XML format based on data from one or several RRD</p>
  32 <p>
  33 </p>
  34 <hr />
  35 <h1><a name="synopsis">SYNOPSIS</a></h1>
  36 <p><strong>rrdtool</strong> <strong>xport</strong>
  37 [<strong>-s</strong>|<strong>--start</strong>&nbsp;<em>seconds</em>]
  38 [<strong>-e</strong>|<strong>--end</strong>&nbsp;<em>seconds</em>]
  39 [<strong>-m</strong>|<strong>--maxrows</strong>&nbsp;<em>rows</em>]
  40 [<strong>--step</strong>&nbsp;<em>value</em>]
  41 [<strong>--daemon</strong>&nbsp;<em>address</em>]
  42 [<strong>DEF:</strong><em>vname</em><strong>=</strong><em>rrd</em><strong>:</strong><em>ds-name</em><strong>:</strong><em>CF</em>]
  43 [<strong>CDEF:</strong><em>vname</em><strong>=</strong><em>rpn-expression</em>]
  44 [<strong>XPORT</strong><strong>:</strong><em>vname</em>[<strong>:</strong><em>legend</em>]]</p>
  45 <p>
  46 </p>
  47 <hr />
  48 <h1><a name="description">DESCRIPTION</a></h1>
  49 <p>The <strong>xport</strong> function's main purpose is to write an XML formatted
  50 representation of the data stored in one or several <strong>RRD</strong>s. It
  51 can also extract numerical reports.</p>
  52 <p>If no <em>XPORT</em> statements are found, there will be no output.</p>
  53 <dl>
  54 <dt><strong><a name="item_seconds"><strong>-s</strong>|<strong>--start</strong> <em>seconds</em> (default end-1day)</a></strong><br />
  55 </dt>
  56 <dd>
  57 The time when the exported range should begin. Time in seconds since
  58 epoch (1970-01-01) is required. Negative numbers are relative to the
  59 current time. By default one day worth of data will be printed.
  60 See also AT-STYLE TIME SPECIFICATION section in the <em>rrdfetch</em>
  61 documentation for a detailed explanation on how to specify time.
  62 </dd>
  63 <p></p>
  64 <dt><strong><strong>-e</strong>|<strong>--end</strong> <em>seconds</em> (default now)</strong><br />
  65 </dt>
  66 <dd>
  67 The time when the exported range should end. Time in seconds since epoch.
  68 See also AT-STYLE TIME SPECIFICATION section in the <em>rrdfetch</em>
  69 documentation for a detailed explanation of ways to specify time.
  70 </dd>
  71 <p></p>
  72 <dt><strong><a name="item_rows"><strong>-m</strong>|<strong>--maxrows</strong> <em>rows</em> (default 400 rows)</a></strong><br />
  73 </dt>
  74 <dd>
  75 This works like the <strong>-w</strong>|<strong>--width</strong> parameter of <em>rrdgraph</em>.
  76 In fact it is exactly the same, but the parameter was renamed to
  77 describe its purpose in this module. See <em>rrdgraph</em> documentation
  78 for details.
  79 </dd>
  80 <p></p>
  81 <dt><strong><a name="item_value"><strong>--step</strong> <em>value</em> (default automatic)</a></strong><br />
  82 </dt>
  83 <dd>
  84 See <a href="././rrdgraph.html">the rrdgraph manpage</a> documentation.
  85 </dd>
  86 <p></p>
  87 <dt><strong><a name="item__2d_2ddaemon_address"><strong>--daemon</strong> <em>address</em></a></strong><br />
  88 </dt>
  89 <dd>
  90 Address of the <a href="././rrdcached.html">the rrdcached manpage</a> daemon. If specified, a <code>flush</code> command is sent
  91 to the server before reading the RRD files. This allows <strong>rrdtool</strong> to return
  92 fresh data even if the daemon is configured to cache values for a long time.
  93 For a list of accepted formats, see the <strong>-l</strong> option in the <a href="././rrdcached.html">the rrdcached manpage</a> manual.
  94 </dd>
  95 <dd>
  96 <pre>
  97   rrdtool xport --daemon unix:/var/run/rrdcached.sock ...</pre>
  98 </dd>
  99 <p></p>
 100 <dt><strong><a name="item__2d_2denumds"><strong>--enumds</strong></a></strong><br />
 101 </dt>
 102 <dd>
 103 The generated xml should contain the data values in enumerated tags.
 104 </dd>
 105 <dd>
 106 <pre>
 107  &lt;v0&gt;val&lt;/v0&gt;&lt;v1&gt;val&lt;/v1&gt;</pre>
 108 </dd>
 109 <p></p>
 110 <dt><strong><a name="item_def_3avname_3drrd_3ads_2dname_3acf"><strong>DEF:</strong><em>vname</em><strong>=</strong><em>rrd</em><strong>:</strong><em>ds-name</em><strong>:</strong><em>CF</em></a></strong><br />
 111 </dt>
 112 <dd>
 113 See <em>rrdgraph</em> documentation.
 114 </dd>
 115 <p></p>
 116 <dt><strong><a name="item_cdef_3avname_3drpn_2dexpression"><strong>CDEF:</strong><em>vname</em><strong>=</strong><em>rpn-expression</em></a></strong><br />
 117 </dt>
 118 <dd>
 119 See <em>rrdgraph</em> documentation.
 120 </dd>
 121 <p></p>
 122 <dt><strong><a name="item_xport_3avname_3a_3alegend"><strong>XPORT:</strong><em>vname</em><strong>:</strong><strong>:</strong><em>legend</em></a></strong><br />
 123 </dt>
 124 <dd>
 125 At least one <em>XPORT</em> statement should be present. The values
 126 referenced by <em>vname</em> are printed. Optionally add a legend.
 127 </dd>
 128 <p></p></dl>
 129 <p>
 130 </p>
 131 <hr />
 132 <h1><a name="output_format">Output format</a></h1>
 133 <p>The output is enclosed in an <strong>xport</strong> element and contains two
 134 blocks. The first block is enclosed by a <strong>meta</strong> element and
 135 contains some meta data. The second block is enclosed by a
 136 <strong>data</strong> element and contains the data rows.</p>
 137 <p>Let's assume that the <em>xport</em> command looks like this:</p>
 138 <pre>
 139   rrdtool xport \
 140           --start now-1h --end now \
 141           DEF:xx=host-inout.lo.rrd:output:AVERAGE \
 142           DEF:yy=host-inout.lo.rrd:input:AVERAGE \
 143           CDEF:aa=xx,yy,+,8,* \
 144           XPORT:xx:&quot;out bytes&quot; \
 145           XPORT:aa:&quot;in and out bits&quot;</pre>
 146 <p>The resulting meta data section is (the values will depend on the
 147 RRD characteristics):</p>
 148 <pre>
 149   &lt;meta&gt;
 150     &lt;start&gt;1020611700&lt;/start&gt;
 151     &lt;step&gt;300&lt;/step&gt;
 152     &lt;end&gt;1020615600&lt;/end&gt;
 153     &lt;rows&gt;14&lt;/rows&gt;
 154     &lt;columns&gt;2&lt;/columns&gt;
 155     &lt;legend&gt;
 156       &lt;entry&gt;out bytes&lt;/entry&gt;
 157       &lt;entry&gt;in and out bits&lt;/entry&gt;
 158     &lt;/legend&gt;
 159   &lt;/meta&gt;</pre>
 160 <p>The resulting data section is:</p>
 161 <pre>
 162   &lt;data&gt;
 163     &lt;row&gt;&lt;t&gt;1020611700&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 164     &lt;row&gt;&lt;t&gt;1020612000&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 165     &lt;row&gt;&lt;t&gt;1020612300&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 166     &lt;row&gt;&lt;t&gt;1020612600&lt;/t&gt;&lt;v&gt;3.4113333333e+00&lt;/v&gt;&lt;v&gt;5.4581333333e+01&lt;/v&gt;&lt;/row&gt;
 167     &lt;row&gt;&lt;t&gt;1020612900&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 168     &lt;row&gt;&lt;t&gt;1020613200&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 169     &lt;row&gt;&lt;t&gt;1020613500&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 170     &lt;row&gt;&lt;t&gt;1020613800&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 171     &lt;row&gt;&lt;t&gt;1020614100&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 172     &lt;row&gt;&lt;t&gt;1020614400&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 173     &lt;row&gt;&lt;t&gt;1020614700&lt;/t&gt;&lt;v&gt;3.7333333333e+00&lt;/v&gt;&lt;v&gt;5.9733333333e+01&lt;/v&gt;&lt;/row&gt;
 174     &lt;row&gt;&lt;t&gt;1020615000&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 175     &lt;row&gt;&lt;t&gt;1020615300&lt;/t&gt;&lt;v&gt;3.4000000000e+00&lt;/v&gt;&lt;v&gt;5.4400000000e+01&lt;/v&gt;&lt;/row&gt;
 176     &lt;row&gt;&lt;t&gt;1020615600&lt;/t&gt;&lt;v&gt;NaN&lt;/v&gt;&lt;v&gt;NaN&lt;/v&gt;&lt;/row&gt;
 177   &lt;/data&gt;</pre>
 178 <p>
 179 </p>
 180 <hr />
 181 <h1><a name="example_1">EXAMPLE 1</a></h1>
 182 <pre>
 183   rrdtool xport \
 184           DEF:out=if1-inouts.rrd:outoctets:AVERAGE \
 185           XPORT:out:&quot;out bytes&quot;</pre>
 186 <p>
 187 </p>
 188 <hr />
 189 <h1><a name="example_2">EXAMPLE 2</a></h1>
 190 <pre>
 191   rrdtool xport \
 192           DEF:out1=if1-inouts.rrd:outoctets:AVERAGE \
 193           DEF:out2=if2-inouts.rrd:outoctets:AVERAGE \
 194           CDEF:sum=out1,out2,+ \
 195           XPORT:out1:&quot;if1 out bytes&quot; \
 196           XPORT:out2:&quot;if2 out bytes&quot; \
 197           XPORT:sum:&quot;output sum&quot;</pre>
 198 <p>
 199 </p>
 200 <hr />
 201 <h1><a name="environment_variables">ENVIRONMENT VARIABLES</a></h1>
 202 <p>The following environment variables may be used to change the behavior of
 203 <code>rrdtoolxport</code>:</p>
 204 <dl>
 205 <dt><strong><a name="item_rrdcached_address"><strong>RRDCACHED_ADDRESS</strong></a></strong><br />
 206 </dt>
 207 <dd>
 208 If this environment variable is set it will have the same effect as specifying
 209 the <code>--daemon</code> option on the command line. If both are present, the command
 210 line argument takes precedence.
 211 </dd>
 212 <p></p></dl>
 213 <p>
 214 </p>
 215 <hr />
 216 <h1><a name="author">AUTHOR</a></h1>
 217 <p>Tobias Oetiker &lt;<a href="mailto:tobi@oetiker.ch">tobi@oetiker.ch</a>&gt;</p>
 218
 219 </body>
 220
 221 </html>