doc/rrdxport.1

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