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-09-25" "1.4.2" "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>