Clone the collectd repo: https://github.com/collectd/collectd.git
An Overview of the architecture of a collectd plugin exists here: https://collectd.org/wiki/index.php/Plugin_architecture
To start off creating a plugin, create a c file under the src directory in collectd, the c file should have:
- A config function
- An init function
- A read function
- A shutdown function
- 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,
sizeof(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 https://wiki.opnfv.org/display/fastpath/Collectd+101 for more info
*
* vl.values_len = 1;
* sstrncpy(vl.host, hostname_g, sizeof(vl.host));
* 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(n.host, hostname_g, sizeof(n.host));
* 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 Makefile.am file to build your plugin
if BUILD_PLUGIN_MY_PLUGIN pkglib_LTLIBRARIES += my_plugin.la my_plugin_la_SOURCES = src/my_plugin.c my_plugin_la_CFLAGS = $(AM_CFLAGS) my_plugin_la_LDFLAGS = $(PLUGIN_LDFLAGS) endif
Under the top level collectd directory Modify the configure.ac 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):
plugin_my_plugin="no"
configure (in configure.ac) your plugin so that it’s enabled on linux under:
# Linux if test "x$ac_system" = "xLinux"; then plugin_my_plugin="yes"
Configure (in configure.ac) your plugin to report if it’s enabled or not:
AC_PLUGIN([my_plugin], [$plugin_my_plugin], [plugin desc])
In configure.ac 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 collectd.conf.in to include:
#@BUILD_PLUGIN_MY_PLUGIN_TRUE@LoadPlugin my_plugin #<Plugin my_plugin> # Option1 true # Option2 “example” #</Plugin>
Under src/ Update the plugin configuration description in collectd.conf.pod
=head2 Plugin C<my_plugin>
The I< my_plugin > plugin collects TBD.
B<Synopsis:>
<Plugin my_plugin>
Option1 true
Option2 “example”
</Plugin>
B<Options:>
=over 2
=item B<Option1> B<false>|B<true>
TBD.
=item B<Option2> I<some_string>
TBD.
=back
you should now be able to build your simple collectd plugin, in the top level directory:
$ ./build.sh $ ./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>
<Plugin my_plugin>
Option1 true
Option2 “example”
</Plugin>
Run collectd:
sbin/collectd -f -C etc/collectd.conf
Extra Challenge:
- Try to add a double plugin configuration option and read it in with: cf_util_get_double
- Write the configuration parameters to the collectd logfile
Statistics in collectd
Statistics in collectd consist of a value list. A value list includes:
| Value list | Example | comment | |||||
|---|---|---|---|---|---|---|---|
| Values | 111112112 | ||||||
| Value length | the number of values in the data set. | ||||||
| Time | timestamp at which the value was collected. | 1475837857 | epoch | ||||
| Interval | interval at which to expect a new value. | 10 | interval | ||||
| Host | used to identify the host. | localhost | can be uuid for vm or host… or can give host a name | ||||
| Plugin | used to identify the plugin. | network | |||||
| Plugin instance (optional) | used to group a set of values together. For e.g. values belonging to a DPDK interface. | eth0 | |||||
| Type | unit 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 data | an 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). | ||||||
| Meta-data. |