"rrdtool update" tells rrdtool what the current value is.
Depending on what kind of data source it is, the number may be used together with the previous one, or it is used as-is. Please be aware that "as-is" does not mean normalization and consolidation are skipped!
Many people use "N", which means "now". This is the most simple case and will work well in many situations.
Sometimes the requirements are a bit more sophisticated. Also often seen is a timestamp, in "seconds since the epoch". This can be used for many purposes. I'll name a few, but there will be many more cases where this can be used:
Two other methods exist: a negative number, which means "n seconds ago", useful if you know there is a fixed amount of delay between when the number was valid and inserting it in the database, and a timestamp according to the AT STYLE time specification as explained in the rrdtool fetch documentation.
Most people will know how many datasources they have in their database, and in what order these were defined (see rrdtool create). In that case just list each datasource in that order.
If you don't know in which order the datasources should be presented, yet you do know which datasources are present and you also happen to know their name, you can tell RRDtool in which order you are going to give the data by use of the template parameter. I don't really see why this is useful (you know much of the layout, yet one detail is unknown?) but if you happen to need it: read the manual and look for template.
If you know you don't know a number, you still do know something. You can tell RRDtool a data source is unknown by giving it "U" as its value. This is useful for instance when you know a device has rebooted, an example follows.
rrdtool update example.rrd N:1:2 rrdtool update example.rrd 1235862000:1:2:3:4:5:U:7 rrdtool update example.rrd "july 9 1998 18:20@3210"
That last example contains quotes. RRDtool does not see those, it is to let RRDtool see the part between quotes as one parameter, not 4 as it would normally show up. In other words: it has to do with shell programming, not with RRDtool. The same example also shows that the separator between time and data is "@" instead of ":". This is so that you can enter time ("18:20") without having to quote the colon.
The promised example for a reboot: you know a reboot occured, and you know it happened 25 seconds ago, and that the current counter values are 100 and 500. What you don't know is what the counter values were just before the reboot, therefore you cannot tell RRDtool what these were and the information is lost forever.
rrdtool update example.rrd -26:U:U rrdtool update example.rrd -25:0:0 rrdtool update example.rrd N:100:500
This does two things: first of all it makes sure you are not going to see a huge spike which could occur if RRDtool thinks the counter wrapped (google for counter wrap), secondly it minimizes the damage, it reduces the amount of unknown data to an absolute minimum.
There's more you may want to know: it is possible to give multiple updates on one single line:
rrdtool update example.rrd 1235775900:0:0 1235776200:100:200 1235776500:400:300
If you need to debug what's going on, you can change "update" in "updatev". This can generate lots of debugging information.
RRDtool will normalize the rates it computed (or got from you, in case of a GAUGE data source type) into what you specified as the step size. But you don't need to update this often if you don't want to.
You need to understand the heartbeat value. This value determines if an update is fresh enough, see rrdtool create if you missed it.
If your heartbeat value allows it, you can span many steps with one single update:
rrdtool update 1235775600:0 rrdtool update 1235818800:1
The time difference is 43200 seconds. If heartbeat is at least that number, then all time slots between 1235775600 and 1235818800 are filled with rate 1. Else, the same time slots will be unknown.
Do you like this information? Tell others! Don't you? Tell me!
This page was created by Alex van den Bogaerdt, an independent IT consultant. If you want to provide feedback or if you want to hire me please see
.