doc/rrdxport.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   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.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  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-03-15" "1.3rc6" "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\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\-\-enumds\fR" 4
 174 .IX Item "--enumds"
 175 The generated xml should contain the data values in enumerated tags.
 176 .Sp
 177 .Vb 1
 178 \& <v0>val</v0><v1>val</v1>
 179 .Ve
 180 .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
 181 .IX Item "DEF:vname=rrd:ds-name:CF"
 182 See \fIrrdgraph\fR documentation.
 183 .IP "\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR" 4
 184 .IX Item "CDEF:vname=rpn-expression"
 185 See \fIrrdgraph\fR documentation.
 186 .IP "\fB\s-1XPORT:\s0\fR\fIvname\fR\fB:\fR\fB:\fR\fIlegend\fR" 4
 187 .IX Item "XPORT:vname::legend"
 188 At least one \fI\s-1XPORT\s0\fR statement should be present. The values
 189 referenced by \fIvname\fR are printed. Optionally add a legend.
 190 .SH "Output format"
 191 .IX Header "Output format"
 192 The output is enclosed in an \fBxport\fR element and contains two
 193 blocks. The first block is enclosed by a \fBmeta\fR element and
 194 contains some meta data. The second block is enclosed by a
 195 \&\fBdata\fR element and contains the data rows.
 196 .PP
 197 Let's assume that the \fIxport\fR command looks like this:
 198 .PP
 199 .Vb 7
 200 \&  rrdtool xport \e
 201 \&          \-\-start now\-1h \-\-end now \e
 202 \&          DEF:xx=host\-inout.lo.rrd:output:AVERAGE \e
 203 \&          DEF:yy=host\-inout.lo.rrd:input:AVERAGE \e
 204 \&          CDEF:aa=xx,yy,+,8,* \e
 205 \&          XPORT:xx:"out bytes" \e
 206 \&          XPORT:aa:"in and out bits"
 207 .Ve
 208 .PP
 209 The resulting meta data section is (the values will depend on the
 210 \&\s-1RRD\s0 characteristics):
 211 .PP
 212 .Vb 11
 213 \&  <meta>
 214 \&    <start>1020611700</start>
 215 \&    <step>300</step>
 216 \&    <end>1020615600</end>
 217 \&    <rows>14</rows>
 218 \&    <columns>2</columns>
 219 \&    <legend>
 220 \&      <entry>out bytes</entry>
 221 \&      <entry>in and out bits</entry>
 222 \&    </legend>
 223 \&  </meta>
 224 .Ve
 225 .PP
 226 The resulting data section is:
 227 .PP
 228 .Vb 16
 229 \&  <data>
 230 \&    <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 231 \&    <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 232 \&    <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 233 \&    <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
 234 \&    <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 235 \&    <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 236 \&    <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 237 \&    <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 238 \&    <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 239 \&    <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 240 \&    <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
 241 \&    <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 242 \&    <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 243 \&    <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
 244 \&  </data>
 245 .Ve
 246 .SH "EXAMPLE 1"
 247 .IX Header "EXAMPLE 1"
 248 .Vb 3
 249 \&  rrdtool xport \e
 250 \&          DEF:out=if1\-inouts.rrd:outoctets:AVERAGE \e
 251 \&          XPORT:out:"out bytes"
 252 .Ve
 253 .SH "EXAMPLE 2"
 254 .IX Header "EXAMPLE 2"
 255 .Vb 7
 256 \&  rrdtool xport \e
 257 \&          DEF:out1=if1\-inouts.rrd:outoctets:AVERAGE \e
 258 \&          DEF:out2=if2\-inouts.rrd:outoctets:AVERAGE \e
 259 \&          CDEF:sum=out1,out2,+ \e
 260 \&          XPORT:out1:"if1 out bytes" \e
 261 \&          XPORT:out2:"if2 out bytes" \e
 262 \&          XPORT:sum:"output sum"
 263 .Ve
 264 .SH "AUTHOR"
 265 .IX Header "AUTHOR"
 266 Tobias Oetiker <tobi@oetiker.ch>