4 Any program that can print a few values to its standard output can become
7 There are 5 lines netdata parses. lines starting with:
9 - `CHART` - create a new chart
10 - `DIMENSION` - add a dimension to the chart just created
11 - `BEGIN` - initialize data collection for a chart
12 - `SET` - set the value of a dimension for the initialized chart
13 - `END` - complete data collection for the initialized chart
15 a single program can produce any number of charts with any number of dimensions
18 charts can also be added any time (not just the beginning).
20 ### command line parameters
22 The plugin should accept just **one** parameter: **the number of seconds it is
23 expected to update the values for its charts**. The value passed by netdata
24 to the plugin is controlled via its configuration file (so there is not need
25 for the plugin to handle this configuration option).
27 The script can overwrite the update frequency. For example, the server may
28 request per second updates, but the script may overwrite this to one update
31 ### environment variables
33 There are a few environment variables that are set by `netdata` and are
34 available for the plugin to use.
38 `NETDATA_CONFIG_DIR`|The directory where all netdata related configuration should be stored. If the plugin requires custom configuration, this is the place to save it.
39 `NETDATA_PLUGINS_DIR`|The directory where all netdata plugins are stored.
40 `NETDATA_WEB_DIR`|The directory where the web files of netdata are saved.
41 `NETDATA_CACHE_DIR`|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.
42 `NETDATA_LOG_DIR`|The directory where the log files are stored. By default the `stderr` output of the plugin will be saved in the `error.log` file of netdata.
43 `NETDATA_HOST_PREFIX`|This is used in environments where system directories like `/sys` and `/proc` have to be accessed at a different path.
44 `NETDATA_DEBUG_FLAGS`|This is number (probably in hex starting with `0x`), that enables certain netdata debugging features.
45 `NETDATA_UPDATE_EVERY`|The minimum number of seconds between chart refreshes. This is like the **internal clock** of netdata (it is user configurable, defaulting to `1`). There is no meaning for a plugin to update its values more frequently than this number of seconds.
48 # the output of the plugin
50 The plugin should output instructions for netdata to its output (`stdout`).
54 `CHART` defines a new chart.
58 > CHART type.id name title units [family [category [charttype [priority [update_every]]]]]
63 uniquely identifies the chart,
64 this is what will be needed to add values to the chart
68 is the name that will be presented to the used for this chart
72 the text above the chart
76 the label of the vertical axis of the chart,
77 all dimensions added to a chart should have the same units
82 is used to group charts together
83 (for example all eth0 charts should say: eth0),
84 if empty or missing, the `id` part of `type.id` will be used
88 the section under which the chart will appear
89 (for example mem.ram should appear in the 'system' section),
90 the special word 'none' means: do not show this chart on the home page,
91 if empty or missing, the `type` part of `type.id` will be used
95 one of `line`, `area` or `stacked`,
96 if empty or missing, the `line` will be used
100 is the relative priority of the charts as rendered on the web page,
101 lower numbers make the charts appear before the ones with higher numbers,
102 if empty or missing, `1000` will be used
106 overwrite the update frequency set by the server,
107 if empty or missing, the user configured value will be used
112 `DIMENSION` defines a new dimension for the chart
116 > DIMENSION id [name [algorithm [multiplier [divisor [hidden]]]]]
122 the `id` of this dimension (it is a text value, not numeric),
123 this will be needed later to add values to the dimension
127 the name of the dimension as it will appear at the legend of the chart,
128 if empty or missing the `id` will be used
136 the value is to drawn as-is (interpolated to second boundary),
137 if `algorithm` is empty, invalid or missing, `absolute` is used
141 the value increases over time,
142 the difference from the last value is presented in the chart,
143 the server interpolates the value and calculates a per second figure
145 * `percentage-of-absolute-row`
147 the % of this value compared to the total of all dimensions
149 * `percentage-of-incremental-row`
151 the % of this value compared to the incremental total of
156 an integer value to multiply the collected value,
157 if empty or missing, `1` is used
161 an integer value to divide the collected value,
162 if empty or missing, `1` is used
166 giving the keyword `hidden` will make this dimension hidden,
167 it will take part in the calculations but will not be presented in the chart
172 data collection is defined as a series of `BEGIN` -> `SET` -> `END` lines
174 > BEGIN type.id [microseconds]
178 is the unique identification of the chart (as given in `CHART`)
182 is the number of microseconds since the last update of the chart,
185 Under heavy system load, the system may have some latency transfering
186 data from the plugins to netdata via the pipe. This number improves
187 accuracy significantly, since the plugin is able to calculate the
188 duration between its iterations better than netdata.
190 The first time the plugin is started, no microseconds should be given
197 is the unique identification of the dimension (of the chart just began)
201 is the collected value
205 END does not take any parameters, it commits the collected values to the chart.
207 More `SET` lines may appear to update all the dimensions of the chart.
208 All of them in one `BEGIN` -> `END` block.
210 All `SET` lines within a single `BEGIN` -> `END` block have to refer to the
213 If more charts need to be updated, each chart should have its own
214 `BEGIN` -> `SET` -> `END` block.
216 If, for any reason, a plugin has issued a `BEGIN` but wants to cancel it,
217 it can issue a `FLUSH`. The `FLUSH` command will instruct netdata to ignore
218 the last `BEGIN` command.
220 If a plugin does not behave properly (outputs invalid lines, or does not
221 follow these guidelines), will be disabled by netdata.
226 netdata will collect any **signed** value in the 64bit range:
227 `-9.223.372.036.854.775.808` to `+9.223.372.036.854.775.807`
229 Internally, all calculations are made using 128 bit double precision and are
230 stored in 30 bits as floating point.
232 If a value is not collected, leave it empty, like this:
236 or do not output the line at all.