Any program that can print a few values to its standard output can become a netdata plugin.
There are 5 lines netdata parses. lines starting with:
CHART- create a new chart
DIMENSION- add a dimension to the chart just created
BEGIN- initialize data collection for a chart
SET- set the value of a dimension for the initialized chart
END- complete data collection for the initialized chart
a single program can produce any number of charts with any number of dimensions each.
charts can also be added any time (not just the beginning).
command line parameters
The plugin should accept just one parameter: the number of seconds it is expected to update the values for its charts. The value passed by netdata to the plugin is controlled via its configuration file (so there is not need for the plugin to handle this configuration option).
The script can overwrite the update frequency. For example, the server may request per second updates, but the script may overwrite this to one update every 5 seconds.
There are a few environment variables that are set by
netdata and are
available for the plugin to use.
||The directory where all netdata related configuration should be stored. If the plugin requires custom configuration, this is the place to save it.|
||The directory where all netdata plugins are stored.|
||The directory where the web files of netdata are saved.|
||The directory where the cache files of netdata are stored. Use this directory if the plugin requires a place to store data. A new directory should be created for the plugin for this purpose, inside this directory.|
||The directory where the log files are stored. By default the
||This is used in environments where system directories like
||This is number (probably in hex starting with
||The minimum number of seconds between chart refreshes. This is like the internal clock of netdata (it is user configurable, defaulting to
the output of the plugin
The plugin should output instructions for netdata to its output (
CHART defines a new chart.
the template is:
CHART type.id name title units [family [category [charttype [priority [update_every]]]]]
uniquely identifies the chart, this is what will be needed to add values to the chart
is the name that will be presented to the used for this chart
the text above the chart
the label of the vertical axis of the chart, all dimensions added to a chart should have the same units of measurement
is used to group charts together (for example all eth0 charts should say: eth0), if empty or missing, the
type.idwill be used
the section under which the chart will appear (for example mem.ram should appear in the 'system' section), the special word 'none' means: do not show this chart on the home page, if empty or missing, the
type.idwill be used
stacked, if empty or missing, the
linewill be used
is the relative priority of the charts as rendered on the web page, lower numbers make the charts appear before the ones with higher numbers, if empty or missing,
1000will be used
overwrite the update frequency set by the server, if empty or missing, the user configured value will be used
DIMENSION defines a new dimension for the chart
the template is:
DIMENSION id [name [algorithm [multiplier [divisor [hidden]]]]]
idof this dimension (it is a text value, not numeric), this will be needed later to add values to the dimension
the name of the dimension as it will appear at the legend of the chart, if empty or missing the
idwill be used
the value is to drawn as-is (interpolated to second boundary), if
algorithmis empty, invalid or missing,
the value increases over time, the difference from the last value is presented in the chart, the server interpolates the value and calculates a per second figure
the % of this value compared to the total of all dimensions
the % of this value compared to the incremental total of all dimensions
an integer value to multiply the collected value, if empty or missing,
an integer value to divide the collected value, if empty or missing,
giving the keyword
hiddenwill make this dimension hidden, it will take part in the calculations but will not be presented in the chart
data collection is defined as a series of
BEGIN type.id [microseconds]
is the unique identification of the chart (as given in
is the number of microseconds since the last update of the chart, it is optional.
Under heavy system load, the system may have some latency transfering data from the plugins to netdata via the pipe. This number improves accuracy significantly, since the plugin is able to calculate the duration between its iterations better than netdata.
The first time the plugin is started, no microseconds should be given to netdata.
SET id = value
is the unique identification of the dimension (of the chart just began)
is the collected value
END does not take any parameters, it commits the collected values to the chart.
SET lines may appear to update all the dimensions of the chart.
All of them in one
SET lines within a single
END block have to refer to the
If more charts need to be updated, each chart should have its own
If, for any reason, a plugin has issued a
BEGIN but wants to cancel it,
it can issue a
FLUSH command will instruct netdata to ignore
If a plugin does not behave properly (outputs invalid lines, or does not follow these guidelines), will be disabled by netdata.
netdata will collect any signed value in the 64bit range:
Internally, all calculations are made using 128 bit double precision and are stored in 30 bits as floating point.
If a value is not collected, leave it empty, like this:
SET id =
or do not output the line at all.