doc/rrdxport.1

   1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
   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 "2013-05-23" "1.4.8" "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\-\-json\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\-\-json\fR" 4
 185 .IX Item "--json"
 186 produce json formated output (instead of xml)
 187 .IP "\fB\-\-enumds\fR" 4
 188 .IX Item "--enumds"
 189 The generated xml should contain the data values in enumerated tags.
 190 .Sp
 191 .Vb 1
 192 \& <v0>val</v0><v1>val</v1>
 193 .Ve
 194 .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
 195 .IX Item "DEF:vname=rrd:ds-name:CF"
 196 See \fIrrdgraph\fR documentation.
 197 .IP "\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR" 4
 198 .IX Item "CDEF:vname=rpn-expression"
 199 See \fIrrdgraph\fR documentation.
 200 .IP "\fB\s-1XPORT:\s0\fR\fIvname\fR\fB:\fR\fB:\fR\fIlegend\fR" 4
 201 .IX Item "XPORT:vname::legend"
 202 At least one \fI\s-1XPORT\s0\fR statement should be present. The values
 203 referenced by \fIvname\fR are printed. Optionally add a legend.
 204 .SH "Output format"
 205 .IX Header "Output format"
 206 The output is enclosed in an \fBxport\fR element and contains two
 207 blocks. The first block is enclosed by a \fBmeta\fR element and
 208 contains some meta data. The second block is enclosed by a
 209 \&\fBdata\fR element and contains the data rows.
 210 .PP
 211 Let's assume that the \fIxport\fR command looks like this:
 212 .PP
 213 .Vb 7
 214 \&  rrdtool xport \e
 215 \&          \-\-start now\-1h \-\-end now \e
 216 \&          DEF:xx=host\-inout.lo.rrd:output:AVERAGE \e
 217 \&          DEF:yy=host\-inout.lo.rrd:input:AVERAGE \e
 218 \&          CDEF:aa=xx,yy,+,8,* \e
 219 \&          XPORT:xx:"out bytes" \e
 220 \&          XPORT:aa:"in and out bits"
 221 .Ve
 222 .PP
 223 The resulting meta data section is (the values will depend on the
 224 \&\s-1RRD\s0 characteristics):
 225 .PP
 226 .Vb 11
 227 \&  <meta>
 228 \&    <start>1020611700</start>
 229 \&    <step>300</step>
 230 \&    <end>1020615600</end>
 231 \&    <rows>14</rows>
 232 \&    <columns>2</columns>
 233 \&    <legend>
 234 \&      <entry>out bytes</entry>
 235 \&      <entry>in and out bits</entry>
 236 \&    </legend>
 237 \&  </meta>
 238 .Ve
 239 .PP
 240 The resulting data section is:
 241 .PP
 242 .Vb 10
 243 \&  <data>
 244 \&    <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 245 \&    <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 246 \&    <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 247 \&    <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
 248 \&    <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 249 \&    <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 250 \&    <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 251 \&    <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 252 \&    <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 253 \&    <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 254 \&    <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
 255 \&    <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 256 \&    <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 257 \&    <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
 258 \&  </data>
 259 .Ve
 260 .SH "EXAMPLE 1"
 261 .IX Header "EXAMPLE 1"
 262 .Vb 3
 263 \&  rrdtool xport \e
 264 \&          DEF:out=if1\-inouts.rrd:outoctets:AVERAGE \e
 265 \&          XPORT:out:"out bytes"
 266 .Ve
 267 .SH "EXAMPLE 2"
 268 .IX Header "EXAMPLE 2"
 269 .Vb 7
 270 \&  rrdtool xport \e
 271 \&          DEF:out1=if1\-inouts.rrd:outoctets:AVERAGE \e
 272 \&          DEF:out2=if2\-inouts.rrd:outoctets:AVERAGE \e
 273 \&          CDEF:sum=out1,out2,+ \e
 274 \&          XPORT:out1:"if1 out bytes" \e
 275 \&          XPORT:out2:"if2 out bytes" \e
 276 \&          XPORT:sum:"output sum"
 277 .Ve
 278 .SH "ENVIRONMENT VARIABLES"
 279 .IX Header "ENVIRONMENT VARIABLES"
 280 The following environment variables may be used to change the behavior of
 281 \&\f(CW\*(C`rrdtool\ xport\*(C'\fR:
 282 .IP "\fB\s-1RRDCACHED_ADDRESS\s0\fR" 4
 283 .IX Item "RRDCACHED_ADDRESS"
 284 If this environment variable is set it will have the same effect as specifying
 285 the \f(CW\*(C`\-\-daemon\*(C'\fR option on the command line. If both are present, the command
 286 line argument takes precedence.
 287 .SH "AUTHOR"
 288 .IX Header "AUTHOR"
 289 Tobias Oetiker <tobi@oetiker.ch>