V5 to v6 migration guide

We're currently working on collectd 6, a new major version of collectd. The release is planned for late 2020.

For the time being, this file topic will contain information needed by developers to migrate existing plugins to the new (internal) API. We may also use this topic to document decisions regarding collectd 6. Eventually information for users looking to migrate an existing setup will be provided here as well.

The following part needs to be proofread and may contain errors!

A metric of type metric_t contains one value of type value_t together with a collection of labels each with a unique name and a string associated with it.

A metric family of type metric_family_t contains a family name and a number of metrics attached to it.

Example:

 static void commit(...) {
  // This is the family where we are going to add the metrics to
 metric_family_t fam = {
      .name = "cpu_usage_percent",
      .type = METRIC_TYPE_GAUGE,
  };

  // Initialize metrics variable
  metric_t m = {0};

  // Set a metrics label and a value, this can be called any number of times.
  // Values for labels which already exist are replaced.
  // Memory is automatically allocated and the metric array is expanded as needed.
  metric_label_set(&m, "cpu", "total");

  // Add another label with a value to the metric
  metric_label_set(&m, "state", cpu_state_names[state]);

  // Associate the metric with all added labels to the metric family
  metric_family_metric_append(&fam, m);

  // Send out the metric
  int status = plugin_dispatch_metric_family(&fam);
  if (status != 0) {
    ERROR("cpu plugin: plugin_dispatch_metric_family failed: %s",
          STRERROR(status));
  }

  // Empty metric labels and family by freeing allocated memory before preparation of next metric
  metric_reset(&m);
  metric_family_metric_reset(&fam);
}