Welcome to the collector configuration reference guide.
This guide contains detailed information about enabling/disabling plugins or modules, in addition a quick reference to the internal plugins API.
Netdata's collector architecture
Netdata has an intricate system for organizing and managing its collectors. Collectors are the processes/programs that actually gather metrics from various sources. Collectors are organized by plugins, which help manage all the independent processes in a variety of programming languages based on their purpose and performance requirements. Modules are a type of collector, used primarily to connect to external applications, such as an Nginx web server or MySQL database, among many others.
For most users, enabling individual collectors for the application/service you're interested in is far more important than knowing which plugin it uses. See our collectors list to see whether your favorite app/service has a collector, and then read the documentation for that specific collector to figure out how to enable it.
There are three types of plugins:
- Internal plugins organize collectors that gather metrics from
/sysand other Linux kernel sources. They are written in
C, and run as threads within the Netdata daemon.
- External plugins organize collectors that gather metrics from external processes, such as a MySQL database or
Nginx web server. They can be written in any language, and the
netdatadaemon spawns them as long-running independent processes. They communicate with the daemon via pipes.
- Plugin orchestrators, which are external plugins that instead support a number of modules. Modules are a type of collector. We have a few plugin orchestrators available for those who want to develop their own collectors, but focus most of our efforts on the Go plugin.
Enable, configure, and disable modules
Most collector modules come with auto-detection, configured to work out-of-the-box on popular operating systems with the default settings.
However, there are cases that auto-detection fails. Usually, the reason is that the applications to be monitored do not
allow Netdata to connect. In most of the cases, allowing the user
localhost to connect and collect
metrics, will automatically enable data collection for the application in question (it will require a Netdata restart).
Troubleshoot a collector
First, navigate to your plugins directory, which is usually at
/usr/libexec/netdata/plugins.d/. If that's not the case
on your system, open
netdata.conf and look for the setting
plugins directory. Once you're in the plugins directory,
switch to the
sudo su -s /bin/bash netdata
The next step is based on the collector's orchestrator. You can figure out which orchestrator the collector uses by
by viewing the collectors list and referencing the configuration file field. For example, if that
go.d, that collector uses the Go orchestrator.
# Go orchestrator (go.d.plugin)
./go.d.plugin -d -m <MODULE_NAME>
# Python orchestrator (python.d.plugin)
./python.d.plugin <MODULE_NAME> debug trace
# Bash orchestrator (bash.d.plugin)
./charts.d.plugin debug 1 <MODULE_NAME>
The output from the relevant command will provide valuable troubleshooting information. If you can't figure out how to enable the collector using the details from this output, feel free to create an issue on our GitHub to get some help from our collectors experts.
Enable and disable plugins
You can enable or disable individual plugins by opening
netdata.conf and scrolling down to the
This section features a list of Netdata's plugins, with a boolean setting to enable or disable them. The exception is
statsd.plugin, which has its own
[statsd] section. Your
[plugins] section should look similar to this:
# proc = yes
# diskspace = yes
# timex = yes
# cgroups = yes
# tc = yes
# idlejitter = yes
# enable running new plugins = yes
# check for new plugins every = 60
# slabinfo = no
# fping = yes
# ioping = yes
# python.d = yes
# go.d = yes
# apps = yes
# perf = yes
# charts.d = yes
By default, most plugins are enabled, so you don't need to enable them explicitly to use their collectors. To enable or
disable any specific plugin, remove the comment (
#) and change the boolean setting to
All external plugins are managed by plugins.d, which provides additional management options.
Each of the internal plugins runs as a thread inside the
netdata daemon. Once this thread has started, the plugin may
spawn additional threads according to its design.
Internal plugins API
The internal data collection API consists of the following calls:
// collect data here (one iteration)
collected_number collected_value = collect_a_value();
// give the metrics to Netdata
static RRDSET *st = NULL; // the chart
static RRDDIM *rd = NULL; // a dimension attached to this chart
// we haven't created this chart before
// create it now
st = rrdset_create_localhost(
, "Chart Title"
// attach a metric to it
rd = rrddim_add(st, "id", "name", multiplier, divider, algorithm);
// this chart is already created
// let Netdata know we start a new iteration on it
// give the collected value(s) to the chart
rrddim_set_by_pointer(st, rd, collected_value);
// signal Netdata we are done with this iteration
Of course, Netdata has a lot of libraries to help you also in collecting the metrics. The best way to find your way through this, is to examine what other similar plugins do.
External plugins use the API and are managed by plugins.d.
Write a custom collector
You can add custom collectors by following the external plugins documentation.