doc/rrdcreate.pod

   1 =head1 NAME
   2
   3 rrdtool create - Set up a new Round Robin Database
   4
   5 =for html <div align="right"><a href="rrdcreate.pdf">PDF</a> version.</div>
   6
   7 =head1 SYNOPSIS
   8
   9 B<rrdtool> B<create> I<filename>
  10 S<[B<--start>|B<-b> I<start time>]>
  11 S<[B<--step>|B<-s> I<step>]>
  12 S<[B<DS:>I<ds-name>B<:>I<DST>B<:>I<heartbeat>B<:>I<min>B<:>I<max>]>
  13 S<[B<RRA:>I<CF>B<:>I<xff>B<:>I<steps>B<:>I<rows>]>
  14
  15 =head1 DESCRIPTION
  16
  17 The create function of the RRDtool lets you set up new
  18 Round Robin Database (B<RRD>) files.
  19 The file is created at its final, full size and filled
  20 with I<*UNKNOWN*> data.
  21
  22 =over 8
  23
  24 =item I<filename>
  25
  26 The name of the B<RRD> you want to create. B<RRD> files should end
  27 with the extension F<.rrd>. However, B<rrdtool> will accept any
  28 filename.
  29
  30 =item B<--start>|B<-b> I<start time> (default: now - 10s)
  31
  32 Specifies the time in seconds since 1970-01-01 UTC when the first
  33 value should be added to the B<RRD>. B<rrdtool> will not accept
  34 any data timed before or at the time specified.
  35
  36 See also AT-STYLE TIME SPECIFICATION section in the
  37 I<rrdfetch> documentation for more ways to specify time.
  38
  39 =item B<--step>|B<-s> I<step> (default: 300 seconds)
  40
  41 Specifies the base interval in seconds with which data will be fed
  42 into the B<RRD>.
  43
  44 =item B<DS:>I<ds-name>B<:>I<DST>B<:>I<heartbeat>B<:>I<min>B<:>I<max>
  45
  46 A single B<RRD> can accept input from several data sources (B<DS>).
  47 (e.g. Incoming and Outgoing traffic on a specific communication
  48 line). With the B<DS> configuration option you must define some basic
  49 properties of each data source you want to use to feed the B<RRD>.
  50
  51 I<ds-name> is the name you will use to reference this particular data
  52 source from an B<RRD>. A I<ds-name> must be 1 to 19 characters long in
  53 the characters [a-zA-Z0-9_].
  54
  55 I<DST> defines the Data Source Type. See the section on "How to Measure" below for further insight.
  56 The Datasource Type must be onw of the following:
  57
  58 =over 4
  59
  60 =item B<GAUGE>
  61
  62 is for things like temperatures or number of people in a
  63 room or value of a RedHat share.
  64
  65 =item B<COUNTER>
  66
  67 is for continuous incrementing counters like the
  68 InOctets counter in a router. The B<COUNTER> data source assumes that
  69 the counter never decreases, except when a counter overflows.  The update
  70 function takes the overflow into account.  The counter is stored as a
  71 per-second rate. When the counter overflows, RRDtool checks if the overflow happened at
  72 the 32bit or 64bit border and acts accordingly by adding an appropriate value to the result.
  73
  74 =item B<DERIVE>
  75
  76 will store the derivative of the line going from the last to the
  77 current value of the data source. This can be useful for gauges, for
  78 example, to measure the rate of people entering or leaving a
  79 room. Internally, derive works exaclty like COUNTER but without
  80 overflow checks. So if your counter does not reset at 32 or 64 bit you
  81 might want to use DERIVE and combine it with a MIN value of 0.
  82
  83 =item B<ABSOLUTE>
  84
  85 is for counters which get reset upon reading. This is used for fast counters
  86 which tend to overflow. So instead of reading them normally you reset them
  87 after every read to make sure you have a maximal time available before the
  88 next overflow. Another usage is for things you count like number of messages
  89 since the last update.
  90
  91 =back
  92
  93 I<heartbeat> defines the maximum number of seconds that may pass
  94 between two updates of this data source before the value of the
  95 data source is assumed to be I<*UNKNOWN*>.
  96
  97 I<min> and I<max> are optional entries defining the expected range of
  98 the data supplied by this data source. If I<min> and/or I<max> are
  99 defined, any value outside the defined range will be regarded as
 100 I<*UNKNOWN*>. If you do not know or care about min and max, set them
 101 to U for unknown. Note that min and max always refer to the processed values
 102 of the DS. For a traffic-B<COUNTER> type DS this would be the max and min
 103 data-rate expected from the device.
 104
 105 I<If information on minimal/maximal expected values is available,
 106 always set the min and/or max properties. This will help RRDtool in
 107 doing a simple sanity check on the data supplied when running update.>
 108
 109 =item B<RRA:>I<CF>B<:>I<xff>B<:>I<steps>B<:>I<rows>
 110
 111 The purpose of an B<RRD> is to store data in the round robin archives
 112 (B<RRA>). An archive consists of a number of data values from all the
 113 defined data-sources (B<DS>) and is defined with an B<RRA> line.
 114
 115 When data is entered into an B<RRD>, it is first fit into time slots of
 116 the length defined with the B<-s> option becoming a I<primary data point>.
 117
 118 The data is also consolidated with the consolidation function (I<CF>)
 119 of the archive. The following consolidation functions are defined:
 120 B<AVERAGE>, B<MIN>, B<MAX>, B<LAST>.
 121
 122 I<xff> The xfiles factor defines what part of a consolidation interval may
 123 be made up from I<*UNKNOWN*> data while the consolidated value is still
 124 regarded as known.
 125
 126 I<steps> defines how many of these I<primary data points> are used to
 127 build a I<consolidated data point> which then goes into the archive.
 128
 129 I<rows> defines how many generations of data values are kept in an B<RRA>.
 130
 131 =back
 132
 133 =head1 The HEARTBEAT and the STEP
 134
 135 Here is an explanation by Don Baarda on the inner workings of rrdtool.
 136 It may help you to sort out why all this *UNKNOWN* data is popping
 137 up in your databases:
 138
 139 RRD gets fed samples at arbitrary times. From these it builds Primary
 140 Data Points (PDPs) at exact times every "step" interval. The PDPs are
 141 then accumulated into RRAs.
 142
 143 The "heartbeat" defines the maximum acceptable interval between
 144 samples. If the interval between samples is less than "heartbeat",
 145 then an average rate is calculated and applied for that interval. If
 146 the interval between samples is longer than "heartbeat", then that
 147 entire interval is considered "unknown". Note that there are other
 148 things that can make a sample interval "unknown", such as the rate
 149 exceeding limits, or even an "unknown" input sample.
 150
 151 The known rates during a PDP's "step" interval are used to calculate
 152 an average rate for that PDP. Also, if the total "unknown" time during
 153 the "step" interval exceeds the "heartbeat", the entire PDP is marked
 154 as "unknown". This means that a mixture of known and "unknown" sample
 155 time in a single PDP "step" may or may not add up to enough "unknown"
 156 time to exceed "heartbeat" and hence mark the whole PDP "unknown". So
 157 "heartbeat" is not only the maximum acceptable interval between
 158 samples, but also the maximum acceptable amount of "unknown" time per
 159 PDP (obviously this is only significant if you have "heartbeat" less
 160 than "step").
 161
 162 The "heartbeat" can be short (unusual) or long (typical) relative to
 163 the "step" interval between PDPs. A short "heartbeat" means you
 164 require multiple samples per PDP, and if you don't get them mark the
 165 PDP unknown. A long heartbeat can span multiple "steps", which means
 166 it is acceptable to have multiple PDPs calculated from a single
 167 sample. An extreme example of this might be a "step" of 5mins and a
 168 "heartbeat" of one day, in which case a single sample every day will
 169 result in all the PDPs for that entire day period being set to the
 170 same average rate. I<-- Don Baarda E<lt>don.baarda@baesystems.comE<gt>>
 171
 172
 173 =head1 HOW TO MEASURE
 174
 175 Here are a few hints on how to measure:
 176
 177 =over
 178
 179
 180 =item Temperature
 181
 182 Normally you have some type of meter you can read to get the temperature.
 183 The temperature is not realy connected with a time. The only connection is
 184 that the temperature reading happened at a certain time. You can use the
 185 B<GAUGE> data source type for this. RRRtool will the record your reading
 186 together with the time.
 187
 188 =item Mail Messages
 189
 190 Assume you have a methode to count the number of messages transported by
 191 your mailserver in a certain amount of time, this give you data like '5
 192 messages in the last 65 seconds'. If you look at the count of 5 like and
 193 B<ABSOLUTE> datatype you can simply update the rrd with the number 5 and the
 194 end time of your monitoring period. RRDtool will then record the number of
 195 messages per second. If at some later stage you want to know the number of
 196 messages transported in a day, you can get the average messages per second
 197 from RRDtool for the day in question and multiply this number with the
 198 number of seconds in a day. Because all math is run with Doubles, the
 199 precision should be acceptable.
 200
 201 =item It's always a Rate
 202
 203 RRDtool stores rates in amount/second for COUNTER, DERIVE and ABSOLUTE data.
 204 When you plot the data, you will get on the y axis amount/second which you
 205 might be tempted to convert to absolute amount volume by multiplying by the
 206 delta-time between the points. RRDtool plots continuous data, and as such is
 207 not appropriate for plotting absolute volumes as for example "total bytes"
 208 sent and received in a router. What you probably want is plot rates that you
 209 can scale to for example bytes/hour or plot volumes with another tool that
 210 draws bar-plots, where the delta-time is clear on the plot for each point
 211 (such that when you read the graph you see for example GB on the y axis,
 212 days on the x axis and one bar for each day).
 213
 214 =back
 215
 216
 217 =head1 EXAMPLE
 218
 219 C<rrdtool create temperature.rrd --step 300 DS:temp:GAUGE:600:-273:5000
 220 RRA:AVERAGE:0.5:1:1200 RRA:MIN:0.5:12:2400 RRA:MAX:0.5:12:2400
 221 RRA:AVERAGE:0.5:12:2400>
 222
 223 This sets up an B<RRD> called F<temperature.rrd> which accepts one
 224 temperature value every 300 seconds. If no new data is supplied for
 225 more than 600 seconds, the temperature becomes I<*UNKNOWN*>.  The
 226 minimum acceptable value is -273 and the maximum is 5000.
 227
 228 A few archives areas are also defined. The first stores the
 229 temperatures supplied for 100 hours (1200 * 300 seconds = 100
 230 hours). The second RRA stores the minimum temperature recorded over
 231 every hour (12 * 300 seconds = 1 hour), for 100 days (2400 hours). The
 232 third and the fourth RRA's do the same with the for the maximum and
 233 average temperature, respectively.
 234
 235 =head1 AUTHOR
 236
 237 Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>