5

I am using rrdtools for storing metrics of my server and want to dump this rrd to XML using rrddump command. so documentation of this XML format is needed, where can i find this?

shreyas
  • 267
  • 1
  • 3
  • 6

3 Answers3

7

There is no documentation specifically for the XML format of RRD files, but it can be derived from the documentation on the binary RRD format as follows:

this guide has been put together from information on the following sites:

Refer also to the documentation on the rrdtool website.

The basic structure of the RRD XML file is:

<rrd> <version /> <step /> <lastupdate />
  <ds> <name /> <type /> <step /> <minimal_heartbeat /> <min /> <max /> <last_ds /> <value /> <unknown_sec /> </ds> ...
  <rra> <cf /> <pdp_per_row /> <xff />
    <cdp_prep> <ds> <value /> <unknown_datapoints /> </ds> ... <cdp_prep>
    <database> <row> <v /> ... </row> ... </database>
  </rra>... 
</rrd>

In this ad hoc syntax definition I have used ellipses (...) to indicate cardinality of the element is 1 or more.

This structure can be described as: each Round Robin Database (< rrd >) has one or more Data Sources (< ds >) and one or more Round Robin Archives (< rra >). Each < rra > contains a Database (< database >) which has multiple rows (< row >). Each < row > has multiple values (< v >), the number of which corresponds to the number of data sources (< ds >) defined for the < rrd >.

The Data Source element (< ds >) defines the data characteristics of each data source (DS) that will be monitored:

  • < name >: free text name for the DS
  • < step >: the sample rate, in seconds, for data collection. Each Primary Data Point (PDP) is assumed to store data at a point in time exactly seconds since the last PDP. If is not specified the default value 300 is used.
  • < type >: the type of measurement captured - { COUNTER | DERIVE | ABSOLUTE | GAUGE } A DS declared as COUNTER will save the rate of change of the value over a step period. This assumes that the value is always increasing (the difference between the current and the previous value is greater than 0). Traffic counters on a router are an ideal candidate for using COUNTER as DST. DERIVE is the same as COUNTER, but it allows negative values as well. If you want to see the rate of change in free disk space on your server, then you might want to use the DERIVE data type. ABSOLUTE also saves the rate of change, but it assumes that the previous value is set to 0. The difference between the current and the previous value is always equal to the current value. GAUGE does not save the rate of change. It saves the actual value itself. There are no divisions or calculations. Memory consumption in a server is a typical example of gauge.
  • < minimal_heartbeat >: the maximum time (in seconds) we can go without an update. For example, if minimal_heartbeat = 120 and we go over 120 seconds without hearing a value, then Primary Data Points for this interval are set to UNKNOWN.
  • < min >: the minimum recordable value for the data source
  • < max >: the maximum recordable value for the data source
  • < last_ds >: ??
  • < value >: ??

The Round Robin Archive element (< rra >) defines the measurement characteristics of each archive in the RRD.

An archive consists of a number of data values or statistics for each of the defined data sources (DS). The elements of an < rra > are:

  • < cf >: the consolidation function for the archive - { AVERAGE | MIN | MAX | LAST }. PDPs are aggregrated or filtered based on the consolidation function.
  • < pdp_per_row >: the number of PDPs that will make up the recorded value. If pdp_per_row is greater than 1, PDPs will be aggregated or filtered based on the < cf >. The product of < pdp_per_row > and DS < step > gives the sample rate in seconds for each record in the < rra >. For example, if the DS < step > = 300 and < pdp_per_row > = 6 the sample rate for the < rra > = 1800 seconds.
  • < xff >: the "XFiles Factor (XFF)". The percentage of PDPs that can be unknown without making the recorded value unknown.
  • < cdp-prep >: ??
  • < database >: the data stored by the < rra >. A < database > consists of multiple < row > elements, each with a number of < v > elements equal to the number of Data Source elements (< ds >) defined for the < rrd >. The < v > elements store the sampled data that is written to an RRD file by the rrdupdate function call - in other words, the data produced by the monitoring tool with which RRD is interfacing.

There are a few elements for which I have not been able to find an explanation. They are marked ??.

Richard Scrivener
  • 86
  • 4
2

If you examine the XML produced by rrddump, and have a basic knowledge of how rrdtool works, the format is quite self-describing. I'm not aware of any documentation.

womble
  • 95,029
  • 29
  • 173
  • 228
0

Have a look at the actual source code comments:

https://github.com/oetiker/rrdtool-1.x/blob/42a4e5bd50898968596d201972b78daef18b855f/src/rrd_format.h#L48

sjas
  • 305
  • 1
  • 4
  • 12