View source for Plugin architecture

This article describes the ''collectd'' plugin architecture. It is aimed at people who want to write a plugin in C.

The plugin structure in itself is not very complicated, but it's easy to forget something anyway. We recommend copying a simple plugin (the [[Plugin:Load|Load plugin]], for example) and start from there.

Here's a walk-through or a checklist of things a plugin needs.

== Copyright notice ==

All <code>*.c</code>-files must include a copyright notice and license information. The license must be compatible to collectd's own license, the GPL&nbsp;2. Unless you have a good reason to split up your plugin into multiple files, please put everything into one <code>.c</code>-file.

== Includes / Header files ==

Usually plugins include at least the following header-files:

<source lang="c">
 #include "collectd.h"
 #include "common.h" /* auxiliary functions */
 #include "plugin.h" /* plugin_register_*, plugin_dispatch_values */
</source>

== Callback functions ==

The initial step for a plugin is to register one or more callback functions. After the shared object has been loaded, the daemon will call the function
<source lang="c">
 void module_register (void);
</source>
that has to be exported by the plugin. The purpose of this function is to register callback functions with the daemon (and nothing else). All functions but <code>module_register</code>, especially all callback functions, should be declared <code>static</code>.

There are the following types of callback functions, that can be registered. Of course, they are all optional.

=== Configuration callbacks ===

If a plugin needs configuration it must provide a configuration callback. There are actually two types of configuration callbacks: ''“simple”'' and ''“complex”''. Both register functions are declared in {{GitFile|src/plugin.h}}.

==== Simple configuration callbacks ====

The ''simple'' configuration callbacks are called for each “configuration item”, i.&nbsp;e. each key-value-pair read from the config file.

The accepted options (keys) must be passed to the registration function. Usually, the options are defined near the beginning of the file similar to this:
<source lang="c">
 static const char *config_keys[] =
 {
   "OptionOne",
   "OptionTwo",
   "SomethingElse"
 };
 static int config_keys_num = STATIC_ARRAY_SIZE (config_keys);
</source>

The callback function must have the following prototype:
<source lang="c">
 static int my_config (const char *key, const char *value);
</source>
The return value must be zero upon success, greater than zero if it failed or less than zero if <code>key</code> has an invalid value.

To register the callback use the <code>plugin_register_config</code> function like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_config ("my_plugin", my_config,
       config_keys, config_keys_num);
 }
</source>

The callback function is called once for each config-item found. There's no guarantee that it's called only once for each option&nbsp;/ key or that it's called at all.

==== Complex configuration callbacks ====

The ''complex'' configuration callbacks are called once for each <code>&lt;Plugin&nbsp;/&gt;</code> block parsed for that plugin. It is passed the entire tree which allows plugins to use nested blocks and provides access to the parsed data types.

The callback function must have the following prototype:
<source lang="c">
 static int my_config (oconfig_item_t *ci);
</source>
The return value must be zero upon success and non-zero if the configuration failed.

To register the callback use the <code>plugin_register_complex_config</code> function like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_complex_config ("my_plugin", my_config);
 }
</source>

For example code on how to handle the configuration tree see the source code of the [[Plugin:SNMP|SNMP plugin]], {{GitFile|src/snmp.c}}.

=== Initialization callbacks ===

The init-function is used to set a plugin up before using it. The init-function is called after the configuration file has been read (i.&nbsp;e. all calls to the config-function have been made) and before any calls to the read- and write-functions.

The callback function must have the following prototype:
<source lang="c">
 static int my_init (void);
</source>
The function has to return zero if successful and non-zero otherwise. If non-zero is returned all functions the plugin registered will be unregistered.

Use the <code>plugin_register_init</code> function to register the callback like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_init ("my_plugin", my_init);
 }
</source>

=== Read callbacks ===

:''→ See also: [[:Category:Callback read]]''

''Read'' callbacks come in two variations: ''“simple”'' and ''“complex”'' read callbacks.

Both callbacks are called periodically, but only once for each registration. So they must be ''thread-safe'' but not ''reentrant-safe'' (unless registered two or more times).

==== Simple read callbacks ====

The callback function must have the following prototype:
<source lang="c">
 static int my_read (void);
</source>
The function has to return zero if successful and non-zero otherwise. If non-zero is returned, the value will be suspended for an increasing interval, but no longer than 86,400&nbsp;seconds (one day).

Use the <code>plugin_register_read</code> function to register the callback like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_read ("my_plugin", my_read);
 }
</source>

==== Complex read callbacks ====

Complex read callbacks differ from simple read callbacks in that they are passed a <code>[[user_data_t]]</code> pointer. This is used for example by the [[Plugin:Java|Java]] plugin (and should be used by [[Plugin:Perl|Perl]] plugin) to decide ''which'' registration was called and call the appropriate opcode&nbsp;/ script implementation.

The callback function must have the following prototype:
<source lang="c">
 static int plugin_read_cb (user_data_t *ud);
</source>
The function has to return zero if successful and non-zero otherwise. If non-zero is returned, the value will be suspended for an increasing interval, but no longer than 86,400&nbsp;seconds (one day).

Use the <code>plugin_register_complex_read</code> function to register the callback. You can pass a <code>struct&nbsp;timespec</code> to the registration function to have the callback called in a specific interval. If you pass <code>NULL</code>, the global ''Interval'' setting will be used.
<source lang="c">
 void module_register (void)                                                                    
 {
   struct timespec ts = { 13, 370000000 }; /* call every 13,37 seconds */
   plugin_register_complex_read ("my_plugin", my_read
       /* interval = */ &ts, /* user data = */ NULL);
 }
</source>

=== Write callbacks ===

Plugins that implement writing of values to somewhere may register a write-function. When a read-function calls <code>plugin_dispatch_values</code> that value-list will be passed to all write-functions together with a data-set, a description of the values. See <code>[[data_set_t]]</code>, <code>[[value_list_t]]</code> and <code>[[user_data_t]]</code> for a description of the data-types. Please note that this function needs to be ''thread-safe''.

The callback function must have the following prototype:
<source lang="c">
 static int my_write (const data_set_t *ds, const value_list_t *vl, user_data_t *ud);


</source>
The function has to return zero if successful and non-zero otherwise.

Use the <code>plugin_register_write</code> function to register the callback like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_write ("my_plugin", my_write, /* user data = */ NULL);
 }
</source>

=== Flush callbacks ===

Many write callbacks do some sort of caching to improve IO-performance. The [[Plugin:RRDtool|RRDtool plugin]] is a prominent example for this. If possible, plugin that implement a write function should also provide a ''flush'' callback to empty those buffers&nbsp;/ caches.

The callback function must have the following prototype:
<source lang="c">
 static int my_flush (int timeout, const char *identifier, user_data_t *ud);
</source>

The callback is expected to flush values that are older than ''timeout'' seconds. Values smaller than or equal to zero indicate that the age should not be checked. If ''identifier'' is not <code>NULL</code>, it is okay only to flush the specified data. The last argument is an optional pointer to state information. See the register function below.

The function has to return zero if successful and non-zero otherwise.

Use the <code>plugin_register_flush</code> function to register the callback like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_flush ("my_plugin", my_flush, /* user data = */ NULL);
 }
</source>

=== Shutdown callbacks ===

Many plugins wish to clean up after themselves. The shutdown-functions can be used to implement that and terminate threads, close files or similar tasks before exiting.

The callback function must have the following prototype:
<source lang="c">
 static int my_shutdown (void);
</source>
The function has to return zero if successful and non-zero otherwise.

Use the <code>plugin_register_shutdown</code> function to register the callback like this:
<source lang="c">
 void module_register (void)                                                                    
 {       
   plugin_register_shutdown ("my_plugin", my_shutdown);
 }
</source>

=== Log callbacks ===

Plugins that implement ''logging'' may register a log-function.
The severity constants <code>LOG_ERR</code>, <code>LOG_WARNING</code>, <code>LOG_NOTICE</code>, <code>LOG_INFO</code>, <code>LOG_DEBUG</code> are defined in {{GitFile|src/plugin.h}}.
The last argument is an optional pointer to state information, see [[user_data_t]] for the data-type description.
Please note that log-function needs to be ''reentrant-safe''!

The callback function must have the following prototype:
<source lang="c">
 static void my_log (int severity, const char *message, user_data_t *ud);
</source>

Use the <code>plugin_register_log()</code> function to register the callback like this:
<source lang="c">
 void module_register (void)
 {
   plugin_register_log ("my_plugin", my_log, /* user data = */ NULL);
 }
</source>

=== Notification callbacks ===

'''todo'''

== Data types ==

There are two complex data types that plugins may encounter. The first one, <code>[[value_list_t]]</code>, is used when passing values from the plugin to the <code>plugin_dispatch_values</code> function from the plugin interface. The second one, <code>[[data_set_t]]</code> occurs in the prototype of write-functions and may come up when dynamically loading data-set-definitions. The declarations can be found in {{GitFile|src/plugin.h}}.

== The interface's stability ==

Please be aware, that the plugin-interface is ''not'' considered part of the backwards compatibility of new minor versions, i.&nbsp;e. it may change pretty much at any time. It will certainly change with the next major version.

It's not as if we change the interface with every other release, but if you want to be really sure that your plugin works next year, ''please send it in''. We will then take care of it and adapt the interface should it change.

[[Category:Development]]