node.d.plugin is a Netdata external plugin. It is an orchestrator for data collection modules written in
- It runs as an independent process
ps faxshows it
- It is started and stopped automatically by Netdata
- It communicates with Netdata via a unidirectional pipe (sending data to the
- Supports any number of data collection modules
- Allows each module to have one or more data collection jobs
- Each job is collecting one or more metrics from a single data source
This is a generic checklist for submitting a new Node.js plugin for Netdata. It is by no means comprehensive.
At minimum, to be buildable and testable, the PR needs to include:
- The module itself, following proper naming conventions:
- A README.md file for the plugin.
- The configuration file for the module
- A basic configuration for the plugin in the appropriate global config file:
conf.d/node.d.conf, which is also in JSON format. If the module should be enabled by default, add a section for it in the
- A line for the plugin in the appropriate
- A line for the plugin configuration file in
- Optionally, chart information in
web/dashboard_info.js. This generally involves specifying a name and icon for the section, and may include descriptions for the section or individual charts.
Node.js is perfect for asynchronous operations. It is very fast and quite common (actually the whole web is based on it). Since data collection is not a CPU intensive task, node.js is an ideal solution for it.
node.d.plugin is a Netdata plugin that provides an abstraction layer to allow easy and quick development of data
collectors in node.js. It also manages all its data collectors (placed in
/usr/libexec/netdata/node.d) using a single
instance of node, thus lowering the memory footprint of data collection.
Of course, there can be independent plugins written in node.js (placed in
These will have to be developed using the guidelines of External Plugins.
node.js plugins you need to have
node installed in your system.
In some older systems, the package named
node is not node.js. It is a terminal emulation program called
In this case the node.js package may be referred as
nodejs. Once you install
nodejs, we suggest to link
/usr/bin/node, so that typing
node in your terminal, opens node.js.
node.d.plugin can work even without any configuration. Its default configuration file is
node.d.conf. To edit it on your system, run
node.d.plugin modules accept configuration in
JSON files do not accept comments. So, the best way to describe them is to have markdown text files
JSON has a very strict formatting. If you get errors from Netdata at
/var/log/netdata/error.log that a certain
configuration file cannot be loaded, we suggest to verify it at http://jsonlint.com/.
The files in this directory, provide usable examples for configuring each
node.d.plugin modules, which are placed in
/usr/libexec/netdata/node.d, you can run
node.d.plugin by hand,
node.d.plugin will run in
debug mode (lots of debug info), with an update frequency of
1 second, evaluating only
the collector scripts
You can define zero or more modules. If none is defined,
node.d.plugin will evaluate all modules available.
Keep in mind that if your configs are not in
/etc/netdata, you should do the following before running
Your data collection module should be split in 3 parts:
a function to fetch the data from its source.
node.d.pluginalready can fetch data from web sources, so you don't need to do anything about it for http.
a function to process the fetched/manipulate the data fetched. This function will make a number of calls to create charts and dimensions and pass the collected values to Netdata. This is the only function you need to write for collecting http JSON data.
updatefunction, which take care of your module configuration and data refresh respectively. You can use the supplied ones.
Your module will automatically be able to process any number of servers, with different settings (even different
data collection frequencies). You will write just the work needed for one and
node.d.plugin will do the rest.
For each server you are going to fetch data from, you will have to create a
service (more later).
To provide a module called
mymodule, you have create the file
/usr/libexec/netdata/node.d/mymodule.node.js, with this structure:
configure(config) is called just once, when
The config file will contain the contents of
This file should have the following format:
If the config file
/etc/netdata/node.d/mymodule.conf does not give a
will be added by
node.d.plugin. So you module will always have them.
The configuration file
/etc/netdata/node.d/mymodule.conf may contain whatever else is needed for
data may be
null or whatever the processor specified in the
service object defines a set of functions to allow you send information to the Netdata core about:
- Charts and dimension definitions
- Updated values, from the collected values
FIXME: document an operational node.d.plugin data collector - the best example is the snmp collector