Skip to content

Value lists

The value_list_t data structure is the main data structure because it is used to pass measured values around inside the daemon. It is often accompanied by data-set-t which is used to describe the stored values in more detail.

The following information is included in the data structure:

  • One or more values of data-sources of undefined type. Only the number of values is included in the structure. What type a specific data source has (for example GAUGE or COUNTER) is described by the data-set-t structure.
  • Fields to uniquely identify the value.
  • The timestamp at which the value was collected.
  • The interval in which new values are to be expected.
  • A pointer to a meta data structure.

The structure is defined in src/daemon/plugin.h. It should be initialized using VALUE_LIST_INIT or VALUE_LIST_STATIC.

Definition of the struct

The structure is defined in src/plugin.h as follows:

 struct value_list_s
 {
   value_t *values;
   int      values_len;
   cdtime_t time;
   cdtime_t interval;
   char     host[DATA_MAX_NAME_LEN];
   char     plugin[DATA_MAX_NAME_LEN];
   char     plugin_instance[DATA_MAX_NAME_LEN];
   char     type[DATA_MAX_NAME_LEN];
   char     type_instance[DATA_MAX_NAME_LEN];
   meta_data_t *meta;
 };
 typedef struct value_list_s value_list_t;

Example

 static void submit (int cpu_num, const char *type_instance, counter_t value)
 {
   value_t values[1];
   value_list_t vl = VALUE_LIST_INIT;

   values[0].counter = value;

   vl.values = values;
   vl.values_len = 1;
   sstrncpy (vl.host, hostname_g, sizeof (vl.host));
   sstrncpy (vl.plugin, "cpu", sizeof (vl.plugin));
   ssnprintf (vl.plugin_instance, sizeof (vl.plugin_instance),
       "%i", cpu_num);
   sstrncpy (vl.type, "cpu", sizeof (vl.type));
   sstrncpy (vl.type_instance, type_instance, sizeof (vl.type_instance));

   plugin_dispatch_values (&vl);
 }

This example initializes, fills and dispatches a value_list_t data structure as seen in nearly every collectd plugin. Please note that neither vl.interval nor vl.time are filled in. In this case the value of interval_g and cdtime() ("now") will be filled in by plugin_dispatch_values(). This is the recommended behavior if these values are applicable.