doc/rrdxport.1

   1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
   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 "2008-03-15" "1.3.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\s-1DEF:\s0\fR\fIvname\fR\fB=\fR\fIrrd\fR\fB:\fR\fIds-name\fR\fB:\fR\fI\s-1CF\s0\fR]
 142 [\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR]
 143 [\fB\s-1XPORT\s0\fR\fB:\fR\fIvname\fR[\fB:\fR\fIlegend\fR]]
 144 .SH "DESCRIPTION"
 145 .IX Header "DESCRIPTION"
 146 The \fBxport\fR function's main purpose is to write an \s-1XML\s0 formatted
 147 representation of the data stored in one or several \fB\s-1RRD\s0\fRs. It
 148 can also extract numerical reports.
 149 .PP
 150 If no \fI\s-1XPORT\s0\fR statements are found, there will be no output.
 151 .IP "\fB\-s\fR|\fB\-\-start\fR \fIseconds\fR (default end\-1day)" 4
 152 .IX Item "-s|--start seconds (default end-1day)"
 153 The time when the exported range should begin. Time in seconds since
 154 epoch (1970\-01\-01) is required. Negative numbers are relative to the
 155 current time. By default one day worth of data will be printed.
 156 See also AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0 section in the \fIrrdfetch\fR
 157 documentation for a detailed explanation on how to specify time.
 158 .IP "\fB\-e\fR|\fB\-\-end\fR \fIseconds\fR (default now)" 4
 159 .IX Item "-e|--end seconds (default now)"
 160 The time when the exported range should end. Time in seconds since epoch.
 161 See also AT-STYLE \s-1TIME\s0 \s-1SPECIFICATION\s0 section in the \fIrrdfetch\fR
 162 documentation for a detailed explanation of ways to specify time.
 163 .IP "\fB\-m\fR|\fB\-\-maxrows\fR \fIrows\fR (default 400 rows)" 4
 164 .IX Item "-m|--maxrows rows (default 400 rows)"
 165 This works like the \fB\-w\fR|\fB\-\-width\fR parameter of \fIrrdgraph\fR.
 166 In fact it is exactly the same, but the parameter was renamed to
 167 describe its purpose in this module. See \fIrrdgraph\fR documentation
 168 for details.
 169 .IP "\fB\-\-step\fR \fIvalue\fR (default automatic)" 4
 170 .IX Item "--step value (default automatic)"
 171 See rrdgraph documentation.
 172 .IP "\fB\-\-enumds\fR" 4
 173 .IX Item "--enumds"
 174 The generated xml should contain the data values in enumerated tags.
 175 .Sp
 176 .Vb 1
 177 \& <v0>val</v0><v1>val</v1>
 178 .Ve
 179 .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
 180 .IX Item "DEF:vname=rrd:ds-name:CF"
 181 See \fIrrdgraph\fR documentation.
 182 .IP "\fB\s-1CDEF:\s0\fR\fIvname\fR\fB=\fR\fIrpn-expression\fR" 4
 183 .IX Item "CDEF:vname=rpn-expression"
 184 See \fIrrdgraph\fR documentation.
 185 .IP "\fB\s-1XPORT:\s0\fR\fIvname\fR\fB:\fR\fB:\fR\fIlegend\fR" 4
 186 .IX Item "XPORT:vname::legend"
 187 At least one \fI\s-1XPORT\s0\fR statement should be present. The values
 188 referenced by \fIvname\fR are printed. Optionally add a legend.
 189 .SH "Output format"
 190 .IX Header "Output format"
 191 The output is enclosed in an \fBxport\fR element and contains two
 192 blocks. The first block is enclosed by a \fBmeta\fR element and
 193 contains some meta data. The second block is enclosed by a
 194 \&\fBdata\fR element and contains the data rows.
 195 .PP
 196 Let's assume that the \fIxport\fR command looks like this:
 197 .PP
 198 .Vb 7
 199 \&  rrdtool xport \e
 200 \&          \-\-start now\-1h \-\-end now \e
 201 \&          DEF:xx=host\-inout.lo.rrd:output:AVERAGE \e
 202 \&          DEF:yy=host\-inout.lo.rrd:input:AVERAGE \e
 203 \&          CDEF:aa=xx,yy,+,8,* \e
 204 \&          XPORT:xx:"out bytes" \e
 205 \&          XPORT:aa:"in and out bits"
 206 .Ve
 207 .PP
 208 The resulting meta data section is (the values will depend on the
 209 \&\s-1RRD\s0 characteristics):
 210 .PP
 211 .Vb 11
 212 \&  <meta>
 213 \&    <start>1020611700</start>
 214 \&    <step>300</step>
 215 \&    <end>1020615600</end>
 216 \&    <rows>14</rows>
 217 \&    <columns>2</columns>
 218 \&    <legend>
 219 \&      <entry>out bytes</entry>
 220 \&      <entry>in and out bits</entry>
 221 \&    </legend>
 222 \&  </meta>
 223 .Ve
 224 .PP
 225 The resulting data section is:
 226 .PP
 227 .Vb 10
 228 \&  <data>
 229 \&    <row><t>1020611700</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 230 \&    <row><t>1020612000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 231 \&    <row><t>1020612300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 232 \&    <row><t>1020612600</t><v>3.4113333333e+00</v><v>5.4581333333e+01</v></row>
 233 \&    <row><t>1020612900</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 234 \&    <row><t>1020613200</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 235 \&    <row><t>1020613500</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 236 \&    <row><t>1020613800</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 237 \&    <row><t>1020614100</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 238 \&    <row><t>1020614400</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 239 \&    <row><t>1020614700</t><v>3.7333333333e+00</v><v>5.9733333333e+01</v></row>
 240 \&    <row><t>1020615000</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 241 \&    <row><t>1020615300</t><v>3.4000000000e+00</v><v>5.4400000000e+01</v></row>
 242 \&    <row><t>1020615600</t><v>NaN</v><v>NaN</v></row>
 243 \&  </data>
 244 .Ve
 245 .SH "EXAMPLE 1"
 246 .IX Header "EXAMPLE 1"
 247 .Vb 3
 248 \&  rrdtool xport \e
 249 \&          DEF:out=if1\-inouts.rrd:outoctets:AVERAGE \e
 250 \&          XPORT:out:"out bytes"
 251 .Ve
 252 .SH "EXAMPLE 2"
 253 .IX Header "EXAMPLE 2"
 254 .Vb 7
 255 \&  rrdtool xport \e
 256 \&          DEF:out1=if1\-inouts.rrd:outoctets:AVERAGE \e
 257 \&          DEF:out2=if2\-inouts.rrd:outoctets:AVERAGE \e
 258 \&          CDEF:sum=out1,out2,+ \e
 259 \&          XPORT:out1:"if1 out bytes" \e
 260 \&          XPORT:out2:"if2 out bytes" \e
 261 \&          XPORT:sum:"output sum"
 262 .Ve
 263 .SH "AUTHOR"
 264 .IX Header "AUTHOR"
 265 Tobias Oetiker <tobi@oetiker.ch>