1RRDCREATE(1) rrdtool RRDCREATE(1)
2
6 rrdcreate - Set up a new Round Robin Database
7
9 rrdtool create filename [--start|-b start time] [--step|-s step]
10 [--template|-t template-file] [--source|-r source-file]
11 [--no-overwrite|-O] [--daemon|-d address] [DS:ds-name[=mapped-ds-
12 name[[source-index]]]:DST:dst arguments] [RRA:CF:cf arguments]
13
15 The create function of RRDtool lets you set up new Round Robin Database
16 (RRD) files. The file is created at its final, full size and filled
17 with *UNKNOWN* data, unless one or more source RRD files have been
18 specified and they hold suitable data to "pre-fill" the new RRD file.
19 filename
21 The name of the RRD you want to create. RRD files should end with the
22 extension .rrd. However, RRDtool will accept any filename.
23 --start|-b start time (default: now - 10s)
25 Specifies the time in seconds since 1970-01-01 UTC when the first value
26 should be added to the RRD. RRDtool will not accept any data timed
27 before or at the time specified.
28 See also "AT-STYLE TIME SPECIFICATION" in rrdfetch for other ways to
30 specify time.
31 If one or more source files is used to pre-fill the new RRD, the
33 --start option may be omitted. In that case, the latest update time
34 among all source files will be used as the last update time of the new
35 RRD file, effectively setting the start time.
36 --step|-s step (default: 300 seconds)
38 Specifies the base interval in seconds with which data will be fed into
39 the RRD. A scaling factor may be present as a suffix to the integer;
40 see "STEP, HEARTBEAT, and Rows As Durations".
41 --no-overwrite|-O
43 Do not clobber an existing file of the same name.
44 --daemon|-d address
46 Address of the rrdcached daemon. For a list of accepted formats, see
47 the -l option in the rrdcached manual.
48 rrdtool create --daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd I<other options>
50 [--template|-t template-file]
52 Specifies a template RRD file to take step, DS and RRA definitions
53 from. This allows one to base the structure of a new file on some
54 existing file. The data of the template file is NOT used for pre-
55 filling, but it is possible to specify the same file as a source file
56 (see below).
57 Additional DS and RRA definitions are permitted, and will be added to
59 those taken from the template.
60 --source|-r source-file
62 One or more source RRD files may be named on the command line. Data
63 from these source files will be used to prefill the created RRD file.
64 The output file and one source file may refer to the same file name.
65 This will effectively replace the source file with the new RRD file.
66 While there is the danger to loose the source file because it gets
67 replaced, there is no danger that the source and the new file may be
68 "garbled" together at any point in time, because the new file will
69 always be created as a temporary file first and will only be moved to
70 its final destination once it has been written in its entirety.
71 Prefilling is done by matching up DS names, RRAs and consolidation
73 functions and choosing the best available data resolution when doing
74 so. Prefilling may not be mathematically correct in all cases (e.g. if
75 resolutions have to change due to changed stepping of the target RRD
76 and old and new resolutions do not match up with old/new bin boundaries
77 in RRAs).
78 In other words: A best effort is made to preserve data during
80 prefilling. Also, pre-filling of RRAs may only be possible for certain
81 kinds of DS types. Prefilling may also have strange effects on Holt-
82 Winters forecasting RRAs. In other words: there is no guarantee for
83 data-correctness.
84 When "pre-filling" a RRD file, the structure of the new file must be
86 specified as usual using DS and RRA specifications as outlined below.
87 Data will be taken from source files based on DS names and types and in
88 the order the source files are specified in. Data sources with the same
89 name from different source files will be combined to form a new data
90 source. Generally, for any point in time the new RRD file will cover
91 after its creation, data from only one source file will have been used
92 for pre-filling. However, data from multiple sources may be combined if
93 it refers to different times or an earlier named source file holds
94 unknown data for a time where a later one holds known data.
95 If this automatic data selection is not desired, the DS syntax allows
97 one to specify a mapping of target and source data sources for
98 prefilling. This syntax allows one to rename data sources and to
99 restrict prefilling for a DS to only use data from a single source
100 file.
101 Prefilling currently only works reliably for RRAs using one of the
103 classic consolidation functions, that is one of: AVERAGE, MIN, MAX,
104 LAST. It might also currently have problems with COMPUTE data sources.
105 Note that the act of prefilling during create is similar to a lot of
107 the operations available via the tune command, but using create syntax.
108 DS:ds-name[=mapped-ds-name[[source-index]]]:DST:dst arguments
110 A single RRD can accept input from several data sources (DS), for
111 example incoming and outgoing traffic on a specific communication line.
112 With the DS configuration option you must define some basic properties
113 of each data source you want to store in the RRD.
114 ds-name is the name you will use to reference this particular data
116 source from an RRD. A ds-name must be 1 to 19 characters long in the
117 characters [a-zA-Z0-9_].
118 DST defines the Data Source Type. The remaining arguments of a data
120 source entry depend on the data source type. For GAUGE, COUNTER,
121 DERIVE, DCOUNTER, DDERIVE and ABSOLUTE the format for a data source
122 entry is:
123 DS:ds-name:{GAUGE | COUNTER | DERIVE | DCOUNTER | DDERIVE |
125 ABSOLUTE}:heartbeat:min:max
126 For COMPUTE data sources, the format is:
128 DS:ds-name:COMPUTE:rpn-expression
130 In order to decide which data source type to use, review the
132 definitions that follow. Also consult the section on "HOW TO MEASURE"
133 for further insight.
134 GAUGE
136 is for things like temperatures or number of people in a room or
137 the value of a RedHat share.
138 COUNTER
140 is for continuous incrementing counters like the ifInOctets counter
141 in a router. The COUNTER data source assumes that the counter never
142 decreases, except when a counter overflows. The update function
143 takes the overflow into account. The counter is stored as a per-
144 second rate. When the counter overflows, RRDtool checks if the
145 overflow happened at the 32bit or 64bit border and acts accordingly
146 by adding an appropriate value to the result.
147 DCOUNTER
149 the same as COUNTER, but for quantities expressed as double-
150 precision floating point number. Could be used to track quantities
151 that increment by non-integer numbers, i.e. number of seconds that
152 some routine has taken to run, total weight processed by some
153 technology equipment etc. The only substantial difference is that
154 DCOUNTER can either be upward counting or downward counting, but
155 not both at the same time. The current direction is detected
156 automatically on the second non-undefined counter update and any
157 further change in the direction is considered a reset. The new
158 direction is determined and locked in by the second update after
159 reset and its difference to the value at reset.
160 DERIVE
162 will store the derivative of the line going from the last to the
163 current value of the data source. This can be useful for gauges,
164 for example, to measure the rate of people entering or leaving a
165 room. Internally, derive works exactly like COUNTER but without
166 overflow checks. So if your counter does not reset at 32 or 64 bit
167 you might want to use DERIVE and combine it with a MIN value of 0.
168 DDERIVE
170 the same as DERIVE, but for quantities expressed as double-
171 precision floating point number.
172 NOTE on COUNTER vs DERIVE
174 by Don Baarda <don.baarda@baesystems.com>
176 If you cannot tolerate ever mistaking the occasional counter reset
178 for a legitimate counter wrap, and would prefer "Unknowns" for all
179 legitimate counter wraps and resets, always use DERIVE with min=0.
180 Otherwise, using COUNTER with a suitable max will return correct
181 values for all legitimate counter wraps, mark some counter resets
182 as "Unknown", but can mistake some counter resets for a legitimate
183 counter wrap.
184 For a 5 minute step and 32-bit counter, the probability of
186 mistaking a counter reset for a legitimate wrap is arguably about
187 0.8% per 1Mbps of maximum bandwidth. Note that this equates to 80%
188 for 100Mbps interfaces, so for high bandwidth interfaces and a
189 32bit counter, DERIVE with min=0 is probably preferable. If you are
190 using a 64bit counter, just about any max setting will eliminate
191 the possibility of mistaking a reset for a counter wrap.
192 ABSOLUTE
194 is for counters which get reset upon reading. This is used for fast
195 counters which tend to overflow. So instead of reading them
196 normally you reset them after every read to make sure you have a
197 maximum time available before the next overflow. Another usage is
198 for things you count like number of messages since the last update.
199 COMPUTE
201 is for storing the result of a formula applied to other data
202 sources in the RRD. This data source is not supplied a value on
203 update, but rather its Primary Data Points (PDPs) are computed from
204 the PDPs of the data sources according to the rpn-expression that
205 defines the formula. Consolidation functions are then applied
206 normally to the PDPs of the COMPUTE data source (that is the rpn-
207 expression is only applied to generate PDPs). In database software,
208 such data sets are referred to as "virtual" or "computed" columns.
209 heartbeat defines the maximum number of seconds that may pass between
211 two updates of this data source before the value of the data source is
212 assumed to be *UNKNOWN*.
213 min and max define the expected range values for data supplied by a
215 data source. If min and/or max are specified any value outside the
216 defined range will be regarded as *UNKNOWN*. If you do not know or care
217 about min and max, set them to U for unknown. Note that min and max
218 always refer to the processed values of the DS. For a traffic-COUNTER
219 type DS this would be the maximum and minimum data-rate expected from
220 the device.
221 If information on minimal/maximal expected values is available, always
223 set the min and/or max properties. This will help RRDtool in doing a
224 simple sanity check on the data supplied when running update.
225 rpn-expression defines the formula used to compute the PDPs of a
227 COMPUTE data source from other data sources in the same <RRD>. It is
228 similar to defining a CDEF argument for the graph command. Please refer
229 to that manual page for a list and description of RPN operations
230 supported. For COMPUTE data sources, the following RPN operations are
231 not supported: COUNT, PREV, TIME, and LTIME. In addition, in defining
232 the RPN expression, the COMPUTE data source may only refer to the names
233 of data source listed previously in the create command. This is similar
234 to the restriction that CDEFs must refer only to DEFs and CDEFs
235 previously defined in the same graph command.
236 When pre-filling the new RRD file using one or more source RRDs, the DS
238 specification may hold an optional mapping after the DS name. This
239 takes the form of an equal sign followed by a mapped-to DS name and an
240 optional source index enclosed in square brackets.
241 For example, the DS
243 DS:a=b[2]:GAUGE:120:0:U
245 specifies that the DS named a should be pre-filled from the DS named b
247 in the second listed source file (source indices are 1-based).
248 RRA:CF:cf arguments
250 The purpose of an RRD is to store data in the round robin archives
251 (RRA). An archive consists of a number of data values or statistics for
252 each of the defined data-sources (DS) and is defined with an RRA line.
253 When data is entered into an RRD, it is first fit into time slots of
255 the length defined with the -s option, thus becoming a primary data
256 point.
257 The data is also processed with the consolidation function (CF) of the
259 archive. There are several consolidation functions that consolidate
260 primary data points via an aggregate function: AVERAGE, MIN, MAX, LAST.
261 AVERAGE
263 the average of the data points is stored.
264 MIN the smallest of the data points is stored.
266 MAX the largest of the data points is stored.
268 LAST
270 the last data points is used.
271 Note that data aggregation inevitably leads to loss of precision and
273 information. The trick is to pick the aggregate function such that the
274 interesting properties of your data is kept across the aggregation
275 process.
276 The format of RRA line for these consolidation functions is:
278 RRA:{AVERAGE | MIN | MAX | LAST}:xff:steps:rows
280 xff The xfiles factor defines what part of a consolidation interval may
282 be made up from *UNKNOWN* data while the consolidated value is still
283 regarded as known. It is given as the ratio of allowed *UNKNOWN* PDPs
284 to the number of PDPs in the interval. Thus, it ranges from 0 to 1
285 (exclusive).
286 steps defines how many of these primary data points are used to build a
288 consolidated data point which then goes into the archive. See also
289 "STEP, HEARTBEAT, and Rows As Durations".
290 rows defines how many generations of data values are kept in an RRA.
292 Obviously, this has to be greater than zero. See also "STEP,
293 HEARTBEAT, and Rows As Durations".
294
296 In addition to the aggregate functions, there are a set of specialized
297 functions that enable RRDtool to provide data smoothing (via the Holt-
298 Winters forecasting algorithm), confidence bands, and the flagging
299 aberrant behavior in the data source time series:
300 • RRA:HWPREDICT:rows:alpha:beta:seasonal period[:rra-num]
302 • RRA:MHWPREDICT:rows:alpha:beta:seasonal period[:rra-num]
304 • RRA:SEASONAL:seasonal period:gamma:rra-
306 num[:smoothing-window=fraction]
307 • RRA:DEVSEASONAL:seasonal period:gamma:rra-
309 num[:smoothing-window=fraction]
310 • RRA:DEVPREDICT:rows:rra-num
312 • RRA:FAILURES:rows:threshold:window length:rra-num
314 These RRAs differ from the true consolidation functions in several
316 ways. First, each of the RRAs is updated once for every primary data
317 point. Second, these RRAs are interdependent. To generate real-time
318 confidence bounds, a matched set of SEASONAL, DEVSEASONAL, DEVPREDICT,
319 and either HWPREDICT or MHWPREDICT must exist. Generating smoothed
320 values of the primary data points requires a SEASONAL RRA and either an
321 HWPREDICT or MHWPREDICT RRA. Aberrant behavior detection requires
322 FAILURES, DEVSEASONAL, SEASONAL, and either HWPREDICT or MHWPREDICT.
323 The predicted, or smoothed, values are stored in the HWPREDICT or
325 MHWPREDICT RRA. HWPREDICT and MHWPREDICT are actually two variations on
326 the Holt-Winters method. They are interchangeable. Both attempt to
327 decompose data into three components: a baseline, a trend, and a
328 seasonal coefficient. HWPREDICT adds its seasonal coefficient to the
329 baseline to form a prediction, whereas MHWPREDICT multiplies its
330 seasonal coefficient by the baseline to form a prediction. The
331 difference is noticeable when the baseline changes significantly in the
332 course of a season; HWPREDICT will predict the seasonality to stay
333 constant as the baseline changes, but MHWPREDICT will predict the
334 seasonality to grow or shrink in proportion to the baseline. The proper
335 choice of method depends on the thing being modeled. For simplicity,
336 the rest of this discussion will refer to HWPREDICT, but MHWPREDICT may
337 be substituted in its place.
338 The predicted deviations are stored in DEVPREDICT (think a standard
340 deviation which can be scaled to yield a confidence band). The FAILURES
341 RRA stores binary indicators. A 1 marks the indexed observation as
342 failure; that is, the number of confidence bounds violations in the
343 preceding window of observations met or exceeded a specified threshold.
344 An example of using these RRAs to graph confidence bounds and failures
345 appears in rrdgraph.
346 The SEASONAL and DEVSEASONAL RRAs store the seasonal coefficients for
348 the Holt-Winters forecasting algorithm and the seasonal deviations,
349 respectively. There is one entry per observation time point in the
350 seasonal cycle. For example, if primary data points are generated every
351 five minutes and the seasonal cycle is 1 day, both SEASONAL and
352 DEVSEASONAL will have 288 rows.
353 In order to simplify the creation for the novice user, in addition to
355 supporting explicit creation of the HWPREDICT, SEASONAL, DEVPREDICT,
356 DEVSEASONAL, and FAILURES RRAs, the RRDtool create command supports
357 implicit creation of the other four when HWPREDICT is specified alone
358 and the final argument rra-num is omitted.
359 rows specifies the length of the RRA prior to wrap around. Remember
361 that there is a one-to-one correspondence between primary data points
362 and entries in these RRAs. For the HWPREDICT CF, rows should be larger
363 than the seasonal period. If the DEVPREDICT RRA is implicitly created,
364 the default number of rows is the same as the HWPREDICT rows argument.
365 If the FAILURES RRA is implicitly created, rows will be set to the
366 seasonal period argument of the HWPREDICT RRA. Of course, the RRDtool
367 resize command is available if these defaults are not sufficient and
368 the creator wishes to avoid explicit creations of the other specialized
369 function RRAs.
370 seasonal period specifies the number of primary data points in a
372 seasonal cycle. If SEASONAL and DEVSEASONAL are implicitly created,
373 this argument for those RRAs is set automatically to the value
374 specified by HWPREDICT. If they are explicitly created, the creator
375 should verify that all three seasonal period arguments agree.
376 alpha is the adaption parameter of the intercept (or baseline)
378 coefficient in the Holt-Winters forecasting algorithm. See rrdtool for
379 a description of this algorithm. alpha must lie between 0 and 1. A
380 value closer to 1 means that more recent observations carry greater
381 weight in predicting the baseline component of the forecast. A value
382 closer to 0 means that past history carries greater weight in
383 predicting the baseline component.
384 beta is the adaption parameter of the slope (or linear trend)
386 coefficient in the Holt-Winters forecasting algorithm. beta must lie
387 between 0 and 1 and plays the same role as alpha with respect to the
388 predicted linear trend.
389 gamma is the adaption parameter of the seasonal coefficients in the
391 Holt-Winters forecasting algorithm (HWPREDICT) or the adaption
392 parameter in the exponential smoothing update of the seasonal
393 deviations. It must lie between 0 and 1. If the SEASONAL and
394 DEVSEASONAL RRAs are created implicitly, they will both have the same
395 value for gamma: the value specified for the HWPREDICT alpha argument.
396 Note that because there is one seasonal coefficient (or deviation) for
397 each time point during the seasonal cycle, the adaptation rate is much
398 slower than the baseline. Each seasonal coefficient is only updated (or
399 adapts) when the observed value occurs at the offset in the seasonal
400 cycle corresponding to that coefficient.
401 If SEASONAL and DEVSEASONAL RRAs are created explicitly, gamma need not
403 be the same for both. Note that gamma can also be changed via the
404 RRDtool tune command.
405 smoothing-window specifies the fraction of a season that should be
407 averaged around each point. By default, the value of smoothing-window
408 is 0.05, which means each value in SEASONAL and DEVSEASONAL will be
409 occasionally replaced by averaging it with its (seasonal period*0.05)
410 nearest neighbors. Setting smoothing-window to zero will disable the
411 running-average smoother altogether.
412 rra-num provides the links between related RRAs. If HWPREDICT is
414 specified alone and the other RRAs are created implicitly, then there
415 is no need to worry about this argument. If RRAs are created
416 explicitly, then carefully pay attention to this argument. For each RRA
417 which includes this argument, there is a dependency between that RRA
418 and another RRA. The rra-num argument is the 1-based index in the order
419 of RRA creation (that is, the order they appear in the create command).
420 The dependent RRA for each RRA requiring the rra-num argument is listed
421 here:
422 • HWPREDICT rra-num is the index of the SEASONAL RRA.
424 • SEASONAL rra-num is the index of the HWPREDICT RRA.
426 • DEVPREDICT rra-num is the index of the DEVSEASONAL RRA.
428 • DEVSEASONAL rra-num is the index of the HWPREDICT RRA.
430 • FAILURES rra-num is the index of the DEVSEASONAL RRA.
432 threshold is the minimum number of violations (observed values outside
434 the confidence bounds) within a window that constitutes a failure. If
435 the FAILURES RRA is implicitly created, the default value is 7.
436 window length is the number of time points in the window. Specify an
438 integer greater than or equal to the threshold and less than or equal
439 to 28. The time interval this window represents depends on the
440 interval between primary data points. If the FAILURES RRA is implicitly
441 created, the default value is 9.
442
444 Traditionally RRDtool specified PDP intervals in seconds, and most
445 other values as either seconds or PDP counts. This made the
446 specification for databases rather opaque; for example
447 rrdtool create power.rrd \
449 --start now-2h --step 1 \
450 DS:watts:GAUGE:300:0:24000 \
451 RRA:AVERAGE:0.5:1:864000 \
452 RRA:AVERAGE:0.5:60:129600 \
453 RRA:AVERAGE:0.5:3600:13392 \
454 RRA:AVERAGE:0.5:86400:3660
455 creates a database of power values collected once per second, with a
457 five minute (300 second) heartbeat, and four RRAs: ten days of one
458 second, 90 days of one minute, 18 months of one hour, and ten years of
459 one day averages.
460 Step, heartbeat, and PDP counts and rows may also be specified as
462 durations, which are positive integers with a single-character suffix
463 that specifies a scaling factor. See "rrd_scaled_duration" in librrd
464 for scale factors of the supported suffixes: "s" (seconds), "m"
465 (minutes), "h" (hours), "d" (days), "w" (weeks), "M" (months), and "y"
466 (years).
467 Scaled step and heartbeat values (which are natively durations in
469 seconds) are used directly, while consolidation function row arguments
470 are divided by their step to produce the number of rows.
471 With this feature the same specification as above can be written as:
473 rrdtool create power.rrd \
475 --start now-2h --step 1s \
476 DS:watts:GAUGE:5m:0:24000 \
477 RRA:AVERAGE:0.5:1s:10d \
478 RRA:AVERAGE:0.5:1m:90d \
479 RRA:AVERAGE:0.5:1h:18M \
480 RRA:AVERAGE:0.5:1d:10y
481
483 Here is an explanation by Don Baarda on the inner workings of RRDtool.
484 It may help you to sort out why all this *UNKNOWN* data is popping up
485 in your databases:
486 RRDtool gets fed samples/updates at arbitrary times. From these it
488 builds Primary Data Points (PDPs) on every "step" interval. The PDPs
489 are then accumulated into the RRAs.
490 The "heartbeat" defines the maximum acceptable interval between
492 samples/updates. If the interval between samples is less than
493 "heartbeat", then an average rate is calculated and applied for that
494 interval. If the interval between samples is longer than "heartbeat",
495 then that entire interval is considered "unknown". Note that there are
496 other things that can make a sample interval "unknown", such as the
497 rate exceeding limits, or a sample that was explicitly marked as
498 unknown.
499 The known rates during a PDP's "step" interval are used to calculate an
501 average rate for that PDP. If the total "unknown" time accounts for
502 more than half the "step", the entire PDP is marked as "unknown". This
503 means that a mixture of known and "unknown" sample times in a single
504 PDP "step" may or may not add up to enough "known" time to warrant a
505 known PDP.
506 The "heartbeat" can be short (unusual) or long (typical) relative to
508 the "step" interval between PDPs. A short "heartbeat" means you require
509 multiple samples per PDP, and if you don't get them mark the PDP
510 unknown. A long heartbeat can span multiple "steps", which means it is
511 acceptable to have multiple PDPs calculated from a single sample. An
512 extreme example of this might be a "step" of 5 minutes and a
513 "heartbeat" of one day, in which case a single sample every day will
514 result in all the PDPs for that entire day period being set to the same
515 average rate. -- Don Baarda <don.baarda@baesystems.com>
516 time|
518 axis|
519 begin__|00|
520 |01|
521 u|02|----* sample1, restart "hb"-timer
522 u|03| /
523 u|04| /
524 u|05| /
525 u|06|/ "hbt" expired
526 u|07|
527 |08|----* sample2, restart "hb"
528 |09| /
529 |10| /
530 u|11|----* sample3, restart "hb"
531 u|12| /
532 u|13| /
533 step1_u|14| /
534 u|15|/ "swt" expired
535 u|16|
536 |17|----* sample4, restart "hb", create "pdp" for step1 =
537 |18| / = unknown due to 10 "u" labeled secs > 0.5 * step
538 |19| /
539 |20| /
540 |21|----* sample5, restart "hb"
541 |22| /
542 |23| /
543 |24|----* sample6, restart "hb"
544 |25| /
545 |26| /
546 |27|----* sample7, restart "hb"
547 step2__|28| /
548 |22| /
549 |23|----* sample8, restart "hb", create "pdp" for step1, create "cdp"
550 |24| /
551 |25| /
552 graphics by vladimir.lavrov@desy.de.
554
556 Here are a few hints on how to measure:
557 Temperature
559 Usually you have some type of meter you can read to get the
560 temperature. The temperature is not really connected with a time.
561 The only connection is that the temperature reading happened at a
562 certain time. You can use the GAUGE data source type for this.
563 RRDtool will then record your reading together with the time.
564 Mail Messages
566 Assume you have a method to count the number of messages
567 transported by your mail server in a certain amount of time, giving
568 you data like '5 messages in the last 65 seconds'. If you look at
569 the count of 5 like an ABSOLUTE data type you can simply update the
570 RRD with the number 5 and the end time of your monitoring period.
571 RRDtool will then record the number of messages per second. If at
572 some later stage you want to know the number of messages
573 transported in a day, you can get the average messages per second
574 from RRDtool for the day in question and multiply this number with
575 the number of seconds in a day. Because all math is run with
576 Doubles, the precision should be acceptable.
577 It's always a Rate
579 RRDtool stores rates in amount/second for COUNTER, DERIVE,
580 DCOUNTER, DDERIVE and ABSOLUTE data. When you plot the data, you
581 will get on the y axis amount/second which you might be tempted to
582 convert to an absolute amount by multiplying by the delta-time
583 between the points. RRDtool plots continuous data, and as such is
584 not appropriate for plotting absolute amounts as for example "total
585 bytes" sent and received in a router. What you probably want is
586 plot rates that you can scale to bytes/hour, for example, or plot
587 absolute amounts with another tool that draws bar-plots, where the
588 delta-time is clear on the plot for each point (such that when you
589 read the graph you see for example GB on the y axis, days on the x
590 axis and one bar for each day).
591
593 rrdtool create temperature.rrd --step 300 \
594 DS:temp:GAUGE:600:-273:5000 \
595 RRA:AVERAGE:0.5:1:1200 \
596 RRA:MIN:0.5:12:2400 \
597 RRA:MAX:0.5:12:2400 \
598 RRA:AVERAGE:0.5:12:2400
599 This sets up an RRD called temperature.rrd which accepts one
601 temperature value every 300 seconds. If no new data is supplied for
602 more than 600 seconds, the temperature becomes *UNKNOWN*. The minimum
603 acceptable value is -273 and the maximum is 5'000.
604 A few archive areas are also defined. The first stores the temperatures
606 supplied for 100 hours (1'200 * 300 seconds = 100 hours). The second
607 RRA stores the minimum temperature recorded over every hour (12 * 300
608 seconds = 1 hour), for 100 days (2'400 hours). The third and the fourth
609 RRA's do the same for the maximum and average temperature,
610 respectively.
611
613 rrdtool create monitor.rrd --step 300 \
614 DS:ifOutOctets:COUNTER:1800:0:4294967295 \
615 RRA:AVERAGE:0.5:1:2016 \
616 RRA:HWPREDICT:1440:0.1:0.0035:288
617 This example is a monitor of a router interface. The first RRA tracks
619 the traffic flow in octets; the second RRA generates the specialized
620 functions RRAs for aberrant behavior detection. Note that the rra-num
621 argument of HWPREDICT is missing, so the other RRAs will implicitly be
622 created with default parameter values. In this example, the forecasting
623 algorithm baseline adapts quickly; in fact the most recent one hour of
624 observations (each at 5 minute intervals) accounts for 75% of the
625 baseline prediction. The linear trend forecast adapts much more slowly.
626 Observations made during the last day (at 288 observations per day)
627 account for only 65% of the predicted linear trend. Note: these
628 computations rely on an exponential smoothing formula described in the
629 LISA 2000 paper.
630 The seasonal cycle is one day (288 data points at 300 second
632 intervals), and the seasonal adaption parameter will be set to 0.1. The
633 RRD file will store 5 days (1'440 data points) of forecasts and
634 deviation predictions before wrap around. The file will store 1 day (a
635 seasonal cycle) of 0-1 indicators in the FAILURES RRA.
636 The same RRD file and RRAs are created with the following command,
638 which explicitly creates all specialized function RRAs using "STEP,
639 HEARTBEAT, and Rows As Durations".
640 rrdtool create monitor.rrd --step 5m \
642 DS:ifOutOctets:COUNTER:30m:0:4294967295 \
643 RRA:AVERAGE:0.5:1:2016 \
644 RRA:HWPREDICT:5d:0.1:0.0035:1d:3 \
645 RRA:SEASONAL:1d:0.1:2 \
646 RRA:DEVSEASONAL:1d:0.1:2 \
647 RRA:DEVPREDICT:5d:5 \
648 RRA:FAILURES:1d:7:9:5
649 Of course, explicit creation need not replicate implicit create, a
651 number of arguments could be changed.
652
654 rrdtool create proxy.rrd --step 300 \
655 DS:Requests:DERIVE:1800:0:U \
656 DS:Duration:DERIVE:1800:0:U \
657 DS:AvgReqDur:COMPUTE:Duration,Requests,0,EQ,1,Requests,IF,/ \
658 RRA:AVERAGE:0.5:1:2016
659 This example is monitoring the average request duration during each 300
661 sec interval for requests processed by a web proxy during the interval.
662 In this case, the proxy exposes two counters, the number of requests
663 processed since boot and the total cumulative duration of all processed
664 requests. Clearly these counters both have some rollover point, but
665 using the DERIVE data source also handles the reset that occurs when
666 the web proxy is stopped and restarted.
667 In the RRD, the first data source stores the requests per second rate
669 during the interval. The second data source stores the total duration
670 of all requests processed during the interval divided by 300. The
671 COMPUTE data source divides each PDP of the AccumDuration by the
672 corresponding PDP of TotalRequests and stores the average request
673 duration. The remainder of the RPN expression handles the divide by
674 zero case.
675
677 Note that new rrd files will have the permission 0644 regardless of
678 your umask setting. If a file with the same name previously exists, its
679 permission settings will be copied to the new file.
680
682 Tobias Oetiker <tobi@oetiker.ch>, Peter Stamfest <peter@stamfest.at>
6831.8.0 2022-03-14 RRDCREATE(1)