Page tree
Skip to end of metadata
Go to start of metadata

Clone the collectd repo:

An Overview of the architecture of a collectd plugin exists here:


To start off creating a plugin, create a c file under the src directory in collectd, the c file should have:

  1. A config function
  2. An init function
  3. A read function
  4. A shutdown function
  5. A function to register callbacks for all the functions above.



#include "collectd.h"
#include "common.h"
#define PLUGIN_NAME "my_plugin"
static _Bool g_enable_option1;
static char g_option2 [DATA_MAX_NAME_LEN];
static int my_config_function(oconfig_item_t *ci) {
  int ret = 0;
  INFO (PLUGIN_NAME ": %s:%d", __FUNCTION__, __LINE__);
  for (int i = 0; i < ci->children_num; i++) {
    oconfig_item_t *child = ci->children + i;
    if (strcasecmp("Option1", child->key) == 0) {
      ret = cf_util_get_boolean(child, & g_enable_option1);
    } else if (strcasecmp("Option2", child->key) == 0) {
      ret = cf_util_get_string_buffer(child, g_option2,
    }else {
      ERROR(PLUGIN_NAME ": Unknown configuration parameter \"%s\".", child->key);
      ret = (-1);
    if (ret != 0) {
      INFO (PLUGIN_NAME ": %s:%d ret=%d", __FUNCTION__, __LINE__, ret);
      return ret;
  return (0);
static int my_read_function(__attribute__((unused)) user_data_t *ud) {
  INFO (PLUGIN_NAME ": %s:%d", __FUNCTION__, __LINE__);
  /*  In order to dispatch values to the collectd daemon you need to fill out a value list and use plugin_dispatch_values() An example is provided below
   *  value_list_t vl = VALUE_LIST_INIT;
   *  vl.values = &(value_t){.derive = value}; //NOTE please change value to the actual value and use an appropriate type: checkout for more info
   *  vl.values_len = 1;
   *  sstrncpy(, hostname_g, sizeof(;
   *  sstrncpy(vl.plugin, PLUGIN_NAME, sizeof(vl.plugin));
   *  sstrncpy(vl.plugin_instance, "my_plugin_instance", sizeof(vl.plugin_instance)); // replace my_plugin_instance with an appropriate string/instance... see the end of this wiki
   *  sstrncpy(vl.type, "my_plugin_type", sizeof(vl.type));// replace my_plugin_type with an appropriate string... see the end of this wiki
   *  plugin_dispatch_values(&vl);
   * To dispatch a notification you need to fill out a notification structure and use plugin_dispatch_notification()
   *  notification_t n = {
   *      .severity = severity, // where severity is one of NOTIF_OKAY, NOTIF_WARNING, NOTIF_FAILURE
   *      .time = cdtime(), 
   *      .message = "Some message",
   *      .plugin = PLUGIN_NAME}; 
   *  sstrncpy(, hostname_g, sizeof(;
   *  sstrncpy(n.plugin_instance, "my_plugin_instance", sizeof(n.plugin_instance)); // replace my_plugin_instance with an appropriate string... see the end of this wiki
   *  plugin_dispatch_notification(&n);

  return (0);
static int my_shutdown_function (void) {
  INFO (PLUGIN_NAME ": %s:%d", __FUNCTION__, __LINE__);
  return (0);
static int my_init_function(void) {
  INFO(PLUGIN_NAME ": %s:%d", __FUNCTION__, __LINE__);
  return (0);
void module_register(void) {
 plugin_register_init("my_plugin", my_init_function);
  plugin_register_complex_config("my_plugin", my_config_function);
  plugin_register_complex_read(NULL, "my_plugin", my_read_function, 0, NULL);
  plugin_register_shutdown("my_plugin", my_shutdown_function);


Under src/ Modify the types.db file to include a new type

my_plugin_type            value:DERIVE:0:U


Under the top level collectd directory Modify the file to build your plugin

my_plugin_la_SOURCES = src/my_plugin.c
my_plugin_la_CFLAGS = $(AM_CFLAGS)
my_plugin_la_LDFLAGS = $(PLUGIN_LDFLAGS)



Under the top level collectd directory Modify the file to include your plugin (search for plugin_ascent="no" and add it in the correct place alphpbetically), and set it to disabled (so it doesn’t build on all platforms):





configure (in  your plugin so that it’s enabled on linux under:

# Linux
if test "x$ac_system" = "xLinux"; then


Configure (in  your plugin to report if it’s enabled or not:

AC_PLUGIN([my_plugin],           [$plugin_my_plugin],     [plugin desc])



In under: “AC_MSG_RESULT([  Modules:])”, enable reporting on the plugin status from the configuration step:

AC_MSG_RESULT([    my_plugin. . . . . . $enable_my_plugin])


Under src/ Finally it’s time to configure the configuration stanzas for your new plugin. By modifygin to include:

#@BUILD_PLUGIN_MY_PLUGIN_TRUE@LoadPlugin my_plugin

#<Plugin my_plugin>
#    Option1 true
#    Option2 “example”



Under src/ Update the plugin configuration description in collectd.conf.pod

=head2 Plugin C<my_plugin>

The I< my_plugin > plugin collects TBD.


  <Plugin my_plugin>
    Option1 true
    Option2 “example”


=over 2

=item B<Option1> B<false>|B<true>


=item B<Option2> I<some_string>




you should now be able to build your simple collectd plugin, in the top level directory:

$ ./
$ ./configure --prefix=$HOME/clct
$ make
$ make -j install


This will install collectd to $HOME/clct.


To run your new plugin:

$ cd $HOME/clct


Edit etc/collectd.conf to include:

LoadPlugin my_plugin
LoadPlugin logfile

<Plugin logfile>
        LogLevel debug
        File STDOUT
        Timestamp true
        PrintSeverity false

<Plugin my_plugin>
    Option1 true
    Option2 “example”


Run collectd:

sbin/collectd -f -C etc/collectd.conf


Extra Challenge:

  1. Try to add a double plugin configuration option and read it in with: cf_util_get_double
  2. Write the configuration parameters to the collectd logfile


Statistics in collectd

Statistics in collectd consist of a value list. A value list includes:


Value listExamplecomment
Values 111112112 
Value lengththe number of values in the data set.  
Timetimestamp at which the value was collected.1475837857epoch
Intervalinterval at which to expect a new value.10interval
Hostused to identify the host.localhostcan be uuid for vm or host… or can give host a name
Pluginused to identify the 
Plugin instance (optional)used to group a set of values together. For e.g. values belonging to a DPDK interface.eth0 
Typeunit used to measure a value. In other words used to refer to a data set.packets 
Type instance (optional)used to distinguish between values that have an identical type.rx or tx 
meta dataan opaque data structure that enables the passing of additional information about a value list. “Meta data in the global cache can be used to store arbitrary information about an identifier”   

Notifications in collectd

Notifications in collectd are generic messages containing:

An associated severity, which can be one of OKAY, WARNING, and FAILURE.
A time.      
A Message     
A host.      
A plugin.      
A plugin instance (optional).    
A type.      
A types instance (optional).    
  • No labels