Writing Plugins - hilbix/netdata GitHub Wiki

netdata supports plugins written in any language. The only requirement netdata has from its plugins, is to be able to print data at their output.

Plugins can be written in the appropriate language for their job. For example:

• You can collect data from JMX, using a java application
• You can collect data from a REST API, using a node.js application
• You can collect data from a system command, using a shell script
• etc.

Many of these languages can run their code efficiently, but they require a lot of resources when they are initialized. netdata suggests that plugins will be initialized once and run forever (until stopped by netdata). This way, the expensive part of their execution, their initialization, is eliminated.

General Plugin Guidelines

Communication with netdata

Plugins' standard output (stdout) is connected through a pipe to netdata. This is how netdata reads values from them.

Plugins' standard error (stderr) is sent to the error log of netdata.

Plugins run forever

Plugins have to be designed in such a way to stay alive for multiple iterations.

This is very important for the resources consumed by netdata as a total. CPU resources are scarce, while memory resources are not to the same degree. Of course there must be a balance, but CPU resources must be respected above all other. So, writing plugins that can stay alive and repeatedly collect and send data to netdata, is the best way of doing it.

Plugins configuration

Netdata will supply the environment variable NETDATA_CONFIG_DIR having the directory where configuration files are stored. It is up to the plugin to read the configuration it needs.

Netdata will also provide the environment variable NETDATA_UPDATE_EVERY, in seconds (the default is 1). This is the minimum update frequency for all charts. A plugin that is updating values more frequently than this, is just wasting resources.

Netdata will call the plugin with just one command line parameter: the number of seconds the user requested this plugin to update its data (by default is also 1).

Other than the above, the plugin configuration is up to the plugin.

Keep in mind, that the user may use netdata configuration to overwrite chart and dimension parameters. This is transparent to the plugin.

Autoconfiguration

Plugins should attempt to autoconfigure themselves when possible.

For example, if your plugin wants to monitor squid, you can search for it on port 3128 or 8080. If any succeeds, you can proceed. If it fails you can output an error (on stderr) saying that you cannot find squid running and giving instructions about the plugin configuration. Then you can stop (exit with non-zero value), so that netdata will not attempt to start the plugin again.

Disabled plugins

Plugins that exit with any value other than zero, will be disabled. Plugins that exit with zero, will be restarted after some time.

Plugins may also be disabled by writing the keyword DISABLE on their output. This keyword must be alone in its line.

Plugins may also be disabled by netdata if they are writing things that netdata does not understand.

Sending data to netdata

Plugins can create any number of charts with any number of dimensions each. Each chart can have its own characteristics independently of the others generated by the same plugin. For example, one chart may have an update frequency of 1 second, another may have 5 seconds and a third may have 10 seconds.