Data source

From collectd Wiki

Jump to: navigation, search

A data source is one entry in a data set. For example, the if_octets data set has two data sources: rx and tx. Each value in a value list corresponds directly to a data source.

A data source consists of four pieces of information about the corresponding value:

  • Name (for example rx and tx)
  • Type of the data source (counter, gauge, derive or absolute, see below)
  • Minimum value (NaN equals negative infinity)
  • Maximum value (NaN equals positive infinity)

If a data set has only one data source, its name is usually simply “value”.

[edit] Definition

The data source structure, data_source_t, is defined in src/plugin.h as follows:

 struct data_source_s
 {
   char   name[DATA_MAX_NAME_LEN];
   int    type;
   double min;
   double max;
 };
 typedef struct data_source_s data_source_t;

[edit] Data source types

There are four data source types which are basically identical to the data source types of the same name in RRDtool:

GAUGE
A GAUGE value is simply stored as-is. This is the right choice for values which may increase as well as decrease, such as temperatures or the amount of memory used.
COUNTER
These data sources are values which hold the total number of something since some “beginning”. For example, the number of octets the were sent / received by an interface since it was brought up. The actual interesting value is the difference between two consecutive readings, divided by the time between the reading, the so called “rate”. (In mathematical terms: One is interested in the derivative of the value.) If the newer number is smaller than the last seen number, a 32-bit or 64-bit wrap-around is assumed and the rate is calculated accordingly. Note: The rate of a COUNTER value is never negative.
DERIVE
These data sources are very similar to COUNTER data sources except that no wrap-around is assumed. Instead, the difference is calculated and assumed valid even if it is negative. This data source type is useful for counters which are possibly reset: Because you're handling a counter, it is save to configure a minimum value of zero. If the counter resets (or wraps around), the difference will be negative and the calculated rate will simply be discarded. With COUNTER you might get inappropriate peaks instead. This data source type is available since version 4.8.
ABSOLUTE
This is probably the most exotic type: It is intended for counters which are reset upon reading. In effect, the type is very similar to GAUGE except that the value is a (signed) integer and will be divided by the time since the last reading. This data source type is available since version 4.8.

For a description of data source types in RRDtool please refer to the rrdcreate(1) manual page.