Skip to content

Data source

Jump to bottom
Florian Forster edited this page Nov 21, 2023 · 1 revision
Clone this wiki locally

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”.

Definition

The data source structure, data_source_t, is defined in src/daemon/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;

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. DERIVE These data sources assume that the change of the value is interesting, i.e. the derivative. Such data sources are very common with events that can be counted, for example the number of emails that have been received per second by an MTA since it was started. The total number of emails is not interesting, but the change since the value has been read the last time. The value is therefore converted to a rate using the following formula (see: Finite difference (Wikipedia)):

    [\textit{rate} = \frac{\textit{value}\mathrm{new} - \textit{value}\mathrm{old}}{\textit{time}\mathrm{new} - \textit{time}\mathrm{old}}]

    Please note that if (\textit{value}\mathrm{new} < \textit{value}\mathrm{old}), the resulting rate will be negative. If you set the minimum value to zero, such data points will be discarded. Using DERIVE data sources and a minimum value of zero is recommended for counters that rarely overflow, i.e. wrap-around after their maximum value has been reached. The rate will be calculated per second. This data source type is available since version-4.8.

  • COUNTER: These data sources behave exactly like DERIVE data sources in the “normal” case. Their behavior differs when (\textit{value}\mathrm{new} < \textit{value}\mathrm{old}), i.e. when the new value is smaller than the previous value. In this case, COUNTER data sources will assume the counter “wrapped around” and take this into account. The formula for wrap-around cases is:

    • (\textit{rate} = \frac{2^\textit{width} - \textit{value}\mathrm{old} + \textit{value}\mathrm{new}}{\textit{time}\mathrm{new} - \textit{time}\mathrm{old}}) \textit{width} = \begin{cases}

32 & \operatorname{if} \quad \textit{value}_\mathrm{old} < 2^{32} \\ 64 & \operatorname{else}

\end{cases}

  • Please note that the rate of a COUNTER data source is never negative. If a counter is reset to zero, for example because an application was restarted, the wrap-around calculation may result in a huge rate. Thus setting a reasonable maximum value is essential when using COUNTER data sources. Because of this, COUNTER data sources are only recommended for counters that wrap-around often, for example 32 bit octet counters of a busy switch port.

  • 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 an (unsigned) integer and will be divided by the time since the last reading. This data source type is available since version-4.8 and has been added mainly for consistency with the data source types available in RRDtool.

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