doc/rrdxport.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "RRDXPORT 1"
 132 .TH RRDXPORT 1 "2008-09-25" "1.3.99909060808" "rrdtool"
 133 .SH "NAME"
 134 rrdxport \- Export data in XML format based on data from one or several RRD
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBrrdtool\fR \fBxport\fR
 138 [\fB\-s\fR|\fB\-\-start\fR\ \fIseconds\fR]
 139 [\fB\-e\fR|\fB\-\-end\fR\ \fIseconds\fR]
 140 [\fB\-m\fR|\fB\-\-maxrows\fR\ \fIrows\fR]
 141 [\fB\-\-step\fR\ \fIvalue\fR]
 142 [\fB\-\-daemon\fR\ \fIaddress\fR]
 143 [\fB\s-1DEF:\s0\fR\fIvname\fR\fB=\fR\fIrrd\fR\fB:\fR\fIds-name\fR\fB:\fR\fI\s-1CF\s0\fR]
 144 [\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR]
 145 [\fB\s-1XPORT\s0\fR\fB:\fR\fIvname\fR[\fB:\fR\fIlegend\fR]]
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 The \fBxport\fR function's main purpose is to write an \s-1XML\s0 formatted
 149 representation of the data stored in one or several \fB\s-1RRD\s0\fRs. It
 150 can also extract numerical reports.
 151 .PP
 152 If no \fI\s-1XPORT\s0\fR statements are found, there will be no output.
 153 .IP "\fB\-s\fR|\fB\-\-start\fR \fIseconds\fR (default end\-1day)" 4
 154 .IX Item "-s|--start seconds (default end-1day)"
 155 The time when the exported range should begin. Time in seconds since
 156 epoch (1970\-01\-01) is required. Negative numbers are relative to the
 157 current time. By default one day worth of data will be printed.
 158 See also AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0 section in the \fIrrdfetch\fR
 159 documentation for a detailed explanation on how to specify time.
 160 .IP "\fB\-e\fR|\fB\-\-end\fR \fIseconds\fR (default now)" 4
 161 .IX Item "-e|--end seconds (default now)"
 162 The time when the exported range should end. Time in seconds since epoch.
 163 See also AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0 section in the \fIrrdfetch\fR
 164 documentation for a detailed explanation of ways to specify time.
 165 .IP "\fB\-m\fR|\fB\-\-maxrows\fR \fIrows\fR (default 400 rows)" 4
 166 .IX Item "-m|--maxrows rows (default 400 rows)"
 167 This works like the \fB\-w\fR|\fB\-\-width\fR parameter of \fIrrdgraph\fR.
 168 In fact it is exactly the same, but the parameter was renamed to
 169 describe its purpose in this module. See \fIrrdgraph\fR documentation
 170 for details.
 171 .IP "\fB\-\-step\fR \fIvalue\fR (default automatic)" 4
 172 .IX Item "--step value (default automatic)"
 173 See rrdgraph documentation.
 174 .IP "\fB\-\-daemon\fR \fIaddress\fR" 4
 175 .IX Item "--daemon address"
 176 Address of the rrdcached daemon. If specified, a \f(CW\*(C`flush\*(C'\fR command is sent
 177 to the server before reading the \s-1RRD\s0 files. This allows \fBrrdtool\fR to return
 178 fresh data even if the daemon is configured to cache values for a long time.
 179 For a list of accepted formats, see the \fB\-l\fR option in the rrdcached manual.
 180 .Sp
 181 .Vb 1
 182 \&  rrdtool xport \-\-daemon unix:/var/run/rrdcached.sock ...
 183 .Ve
 184 .IP "\fB\-\-enumds\fR" 4
 185 .IX Item "--enumds"
 186 The generated xml should contain the data values in enumerated tags.
 187 .Sp
 188 .Vb 1
 189 \& <v0>val</v0><v1>val</v1>
 190 .Ve
 191 .IP "\fB\s-1DEF:\s0\fR\fIvname\fR\fB=\fR\fIrrd\fR\fB:\fR\fIds-name\fR\fB:\fR\fI\s-1CF\s0\fR" 4
 192 .IX Item "DEF:vname=rrd:ds-name:CF"
 193 See \fIrrdgraph\fR documentation.
 194 .IP "\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR" 4
 195 .IX Item "CDEF:vname=rpn-expression"
 196 See \fIrrdgraph\fR documentation.
 197 .IP "\fB\s-1XPORT:\s0\fR\fIvname\fR\fB:\fR\fB:\fR\fIlegend\fR" 4
 198 .IX Item "XPORT:vname::legend"
 199 At least one \fI\s-1XPORT\s0\fR statement should be present. The values
 200 referenced by \fIvname\fR are printed. Optionally add a legend.
 201 .SH "Output format"
 202 .IX Header "Output format"
 203 The output is enclosed in an \fBxport\fR element and contains two
 204 blocks. The first block is enclosed by a \fBmeta\fR element and
 205 contains some meta data. The second block is enclosed by a
 206 \&\fBdata\fR element and contains the data rows.
 207 .PP
 208 Let's assume that the \fIxport\fR command looks like this:
 209 .PP
 210 .Vb 7
 211 \&  rrdtool xport \e
 212 \&          \-\-start now\-1h \-\-end now \e
 213 \&          DEF:xx=host\-inout.lo.rrd:output:AVERAGE \e
 214 \&          DEF:yy=host\-inout.lo.rrd:input:AVERAGE \e
 215 \&          CDEF:aa=xx,yy,+,8,* \e
 216 \&          XPORT:xx:"out bytes" \e
 217 \&          XPORT:aa:"in and out bits"
 218 .Ve
 219 .PP
 220 The resulting meta data section is (the values will depend on the
 221 \&\s-1RRD\s0 characteristics):
 222 .PP
 223 .Vb 11
 224 \&  <meta>
 225 \&    <start>1020611700</start>
 226 \&    <step>300</step>
 227 \&    <end>1020615600</end>
 228 \&    <rows>14</rows>
 229 \&    <columns>2</columns>
 230 \&    <legend>
 231 \&      <entry>out bytes</entry>
 232 \&      <entry>in and out bits</entry>
 233 \&    </legend>
 234 \&  </meta>
 235 .Ve
 236 .PP
 237 The resulting data section is:
 238 .PP
 239 .Vb 16
 240 \&  <data>
 241 \&    <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 242 \&    <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 243 \&    <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 244 \&    <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
 245 \&    <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 246 \&    <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 247 \&    <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 248 \&    <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 249 \&    <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 250 \&    <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 251 \&    <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
 252 \&    <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 253 \&    <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 254 \&    <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
 255 \&  </data>
 256 .Ve
 257 .SH "EXAMPLE 1"
 258 .IX Header "EXAMPLE 1"
 259 .Vb 3
 260 \&  rrdtool xport \e
 261 \&          DEF:out=if1\-inouts.rrd:outoctets:AVERAGE \e
 262 \&          XPORT:out:"out bytes"
 263 .Ve
 264 .SH "EXAMPLE 2"
 265 .IX Header "EXAMPLE 2"
 266 .Vb 7
 267 \&  rrdtool xport \e
 268 \&          DEF:out1=if1\-inouts.rrd:outoctets:AVERAGE \e
 269 \&          DEF:out2=if2\-inouts.rrd:outoctets:AVERAGE \e
 270 \&          CDEF:sum=out1,out2,+ \e
 271 \&          XPORT:out1:"if1 out bytes" \e
 272 \&          XPORT:out2:"if2 out bytes" \e
 273 \&          XPORT:sum:"output sum"
 274 .Ve
 275 .SH "ENVIRONMENT VARIABLES"
 276 .IX Header "ENVIRONMENT VARIABLES"
 277 The following environment variables may be used to change the behavior of
 278 \&\f(CW\*(C`rrdtool\ xport\*(C'\fR:
 279 .IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
 280 .IX Item "RRDCACHED_ADDRESS"
 281 If this environment variable is set it will have the same effect as specifying
 282 the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
 283 line argument takes precedence.
 284 .SH "AUTHOR"
 285 .IX Header "AUTHOR"
 286 Tobias Oetiker <tobi@oetiker.ch>