1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
|
<!--
title: "External plugins overview"
custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/plugins.d/README.md"
sidebar_label: "plugins.d"
learn_status: "Published"
learn_topic_type: "References"
learn_rel_path: "References/Collectors references/plugins.d"
-->
# External plugins overview
`plugins.d` is the Netdata internal plugin that collects metrics
from external processes, thus allowing Netdata to use **external plugins**.
## Provided External Plugins
|plugin|language|O/S|description|
|:----:|:------:|:-:|:----------|
|[apps.plugin](https://github.com/netdata/netdata/blob/master/collectors/apps.plugin/README.md)|`C`|linux, freebsd|monitors the whole process tree on Linux and FreeBSD and breaks down system resource usage by **process**, **user** and **user group**.|
|[charts.d.plugin](https://github.com/netdata/netdata/blob/master/collectors/charts.d.plugin/README.md)|`BASH`|all|a **plugin orchestrator** for data collection modules written in `BASH` v4+.|
|[cups.plugin](https://github.com/netdata/netdata/blob/master/collectors/cups.plugin/README.md)|`C`|all|monitors **CUPS**|
|[ebpf.plugin](https://github.com/netdata/netdata/blob/master/collectors/ebpf.plugin/README.md)|`C`|linux|monitors different metrics on environments using kernel internal functions.|
|[go.d.plugin](https://github.com/netdata/go.d.plugin/blob/master/README.md)|`GO`|all|collects metrics from the system, applications, or third-party APIs.|
|[ioping.plugin](https://github.com/netdata/netdata/blob/master/collectors/ioping.plugin/README.md)|`C`|all|measures disk latency.|
|[freeipmi.plugin](https://github.com/netdata/netdata/blob/master/collectors/freeipmi.plugin/README.md)|`C`|linux|collects metrics from enterprise hardware sensors, on Linux servers.|
|[nfacct.plugin](https://github.com/netdata/netdata/blob/master/collectors/nfacct.plugin/README.md)|`C`|linux|collects netfilter firewall, connection tracker and accounting metrics using `libmnl` and `libnetfilter_acct`.|
|[xenstat.plugin](https://github.com/netdata/netdata/blob/master/collectors/xenstat.plugin/README.md)|`C`|linux|collects XenServer and XCP-ng metrics using `lxenstat`.|
|[perf.plugin](https://github.com/netdata/netdata/blob/master/collectors/perf.plugin/README.md)|`C`|linux|collects CPU performance metrics using performance monitoring units (PMU).|
|[python.d.plugin](https://github.com/netdata/netdata/blob/master/collectors/python.d.plugin/README.md)|`python`|all|a **plugin orchestrator** for data collection modules written in `python` v2 or v3 (both are supported).|
|[slabinfo.plugin](https://github.com/netdata/netdata/blob/master/collectors/slabinfo.plugin/README.md)|`C`|linux|collects kernel internal cache objects (SLAB) metrics.|
Plugin orchestrators may also be described as **modular plugins**. They are modular since they accept custom made modules to be included. Writing modules for these plugins is easier than accessing the native Netdata API directly. You will find modules already available for each orchestrator under the directory of the particular modular plugin (e.g. under python.d.plugin for the python orchestrator).
Each of these modular plugins has each own methods for defining modules. Please check the examples and their documentation.
## Motivation
This plugin allows Netdata to use **external plugins** for data collection:
1. external data collection plugins may be written in any computer language.
2. external data collection plugins may use O/S capabilities or `setuid` to
run with escalated privileges (compared to the `netdata` daemon).
The communication between the external plugin and Netdata is unidirectional
(from the plugin to Netdata), so that Netdata cannot manipulate an external
plugin running with escalated privileges.
## Operation
Each of the external plugins is expected to run forever.
Netdata will start it when it starts and stop it when it exits.
If the external plugin exits or crashes, Netdata will log an error.
If the external plugin exits or crashes without pushing metrics to Netdata, Netdata will not start it again.
- 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 Netdata if they output things that Netdata does not understand.
The `stdout` of external plugins is connected to Netdata to receive metrics,
with the API defined below.
The `stderr` of external plugins is connected to Netdata's `error.log`.
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.
## Configuration
Netdata will supply the environment variables `NETDATA_USER_CONFIG_DIR` (for user supplied) and `NETDATA_STOCK_CONFIG_DIR` (for Netdata supplied) configuration files to identify the directory where configuration files are stored. It is up to the plugin to read the configuration it needs.
The `netdata.conf` section `[plugins]` section contains a list of all the plugins found at the system where Netdata runs, with a boolean setting to enable them or not.
Example:
```
[plugins]
# enable running new plugins = yes
# check for new plugins every = 60
# charts.d = yes
# ioping = yes
# python.d = yes
```
The setting `enable running new plugins` sets the default behavior for all external plugins. It can be
overridden for distinct plugins by modifying the appropriate plugin value configuration to either `yes` or `no`.
The setting `check for new plugins every` sets the interval between scans of the directory
`/usr/libexec/netdata/plugins.d`. New plugins can be added any time, and Netdata will detect them in a timely manner.
For each of the external plugins enabled, another `netdata.conf` section
is created, in the form of `[plugin:NAME]`, where `NAME` is the name of the external plugin.
This section allows controlling the update frequency of the plugin and provide
additional command line arguments to it.
For example, for `apps.plugin` the following section is available:
```
[plugin:apps]
# update every = 1
# command options =
```
- `update every` controls the granularity of the external plugin.
- `command options` allows giving additional command line options to the plugin.
Netdata will provide to the external plugins 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.
## External Plugins API
Any program that can print a few values to its standard output can become a Netdata external plugin.
Netdata parses lines starting with:
- `CHART` - create or update a chart
- `DIMENSION` - add or update a dimension to the chart just created
- `VARIABLE` - define a variable (to be used in health calculations)
- `CLABEL` - add a label to a chart
- `CLABEL_COMMIT` - commit added labels to the chart
- `FUNCTION` - define a function that can be called later to execute it
- `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
- `FLUSH` - ignore the last collected values
- `DISABLE` - disable this plugin
a single program can produce any number of charts with any number of dimensions each.
Charts can be added any time (not just the beginning).
### command line parameters
The plugin **MUST** 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 no need
for the plugin to handle this configuration option).
The external plugin can overwrite the update frequency. For example, the server may
request per second updates, but the plugin may ignore it and update its charts
every 5 seconds.
### environment variables
There are a few environment variables that are set by `netdata` and are
available for the plugin to use.
|variable|description|
|:------:|:----------|
|`NETDATA_USER_CONFIG_DIR`|The directory where all Netdata-related user configuration should be stored. If the plugin requires custom user configuration, this is the place the user has saved it (normally under `/etc/netdata`).|
|`NETDATA_STOCK_CONFIG_DIR`|The directory where all Netdata -related stock configuration should be stored. If the plugin is shipped with configuration files, this is the place they can be found (normally under `/usr/lib/netdata/conf.d`).|
|`NETDATA_PLUGINS_DIR`|The directory where all Netdata plugins are stored.|
|`NETDATA_USER_PLUGINS_DIRS`|The list of directories where custom plugins are stored.|
|`NETDATA_WEB_DIR`|The directory where the web files of Netdata are saved.|
|`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.|
|`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.|
|`NETDATA_HOST_PREFIX`|This is used in environments where system directories like `/sys` and `/proc` have to be accessed at a different path.|
|`NETDATA_DEBUG_FLAGS`|This is a number (probably in hex starting with `0x`), that enables certain Netdata debugging features. Check **\[[Tracing Options]]** for more information.|
|`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.|
### The output of the plugin
The plugin should output instructions for Netdata to its output (`stdout`). Since this uses pipes, please make sure you flush stdout after every iteration.
#### DISABLE
`DISABLE` will disable this plugin. This will prevent Netdata from restarting the plugin. You can also exit with the value `1` to have the same effect.
#### CHART
`CHART` defines a new chart.
the template is:
> CHART type.id name title units \[family \[context \[charttype \[priority \[update_every \[options \[plugin [module]]]]]]]]
where:
- `type.id`
uniquely identifies the chart,
this is what will be needed to add values to the chart
the `type` part controls the menu the charts will appear in
- `name`
is the name that will be presented to the user instead of `id` in `type.id`. This means that only the `id` part of
`type.id` is changed. When a name has been given, the chart is indexed (and can be referred) as both `type.id` and
`type.name`. You can set name to `''`, or `null`, or `(null)` to disable it. If a chart with the same name already
exists, a serial number is automatically attached to the name to avoid naming collisions.
- `title`
the text above the chart
- `units`
the label of the vertical axis of the chart,
all dimensions added to a chart should have the same units
of measurement
- `family`
is used to group charts together
(for example all eth0 charts should say: eth0),
if empty or missing, the `id` part of `type.id` will be used
this controls the sub-menu on the dashboard
- `context`
the context is giving the template of the chart. For example, if multiple charts present the same information for a different family, they should have the same `context`
this is used for looking up rendering information for the chart (colors, sizes, informational texts) and also apply alarms to it
- `charttype`
one of `line`, `area` or `stacked`,
if empty or missing, the `line` will be used
- `priority`
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, `1000` will be used
- `update_every`
overwrite the update frequency set by the server,
if empty or missing, the user configured value will be used
- `options`
a space separated list of options, enclosed in quotes. 4 options are currently supported: `obsolete` to mark a chart as obsolete (Netdata will hide it and delete it after some time), `detail` to mark a chart as insignificant (this may be used by dashboards to make the charts smaller, or somehow visualize properly a less important chart), `store_first` to make Netdata store the first collected value, assuming there was an invisible previous value set to zero (this is used by statsd charts - if the first data collected value of incremental dimensions is not zero based, unrealistic spikes will appear with this option set) and `hidden` to perform all operations on a chart, but do not offer it on dashboards (the chart will be send to external databases). `CHART` options have been added in Netdata v1.7 and the `hidden` option was added in 1.10.
- `plugin` and `module`
both are just names that are used to let the user identify the plugin and the module that generated the chart. If `plugin` is unset or empty, Netdata will automatically set the filename of the plugin that generated the chart. `module` has not default.
#### DIMENSION
`DIMENSION` defines a new dimension for the chart
the template is:
> DIMENSION id \[name \[algorithm \[multiplier \[divisor [options]]]]]
where:
- `id`
the `id` of this dimension (it is a text value, not numeric),
this will be needed later to add values to the dimension
We suggest to avoid using `.` in dimension ids. External databases expect metrics to be `.` separated and people will get confused if a dimension id contains a dot.
- `name`
the name of the dimension as it will appear at the legend of the chart,
if empty or missing the `id` will be used
- `algorithm`
one of:
- `absolute`
the value is to drawn as-is (interpolated to second boundary),
if `algorithm` is empty, invalid or missing, `absolute` is used
- `incremental`
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
- `percentage-of-absolute-row`
the % of this value compared to the total of all dimensions
- `percentage-of-incremental-row`
the % of this value compared to the incremental total of
all dimensions
- `multiplier`
an integer value to multiply the collected value,
if empty or missing, `1` is used
- `divisor`
an integer value to divide the collected value,
if empty or missing, `1` is used
- `options`
a space separated list of options, enclosed in quotes. Options supported: `obsolete` to mark a dimension as obsolete (Netdata will delete it after some time) and `hidden` to make this dimension hidden, it will take part in the calculations but will not be presented in the chart.
#### VARIABLE
> VARIABLE [SCOPE] name = value
`VARIABLE` defines a variable that can be used in alarms. This is to used for setting constants (like the max connections a server may accept).
Variables support 2 scopes:
- `GLOBAL` or `HOST` to define the variable at the host level.
- `LOCAL` or `CHART` to define the variable at the chart level. Use chart-local variables when the same variable may exist for different charts (i.e. Netdata monitors 2 mysql servers, and you need to set the `max_connections` each server accepts). Using chart-local variables is the ideal to build alarm templates.
The position of the `VARIABLE` line, sets its default scope (in case you do not specify a scope). So, defining a `VARIABLE` before any `CHART`, or between `END` and `BEGIN` (outside any chart), sets `GLOBAL` scope, while defining a `VARIABLE` just after a `CHART` or a `DIMENSION`, or within the `BEGIN` - `END` block of a chart, sets `LOCAL` scope.
These variables can be set and updated at any point.
Variable names should use alphanumeric characters, the `.` and the `_`.
The `value` is floating point (Netdata used `long double`).
Variables are transferred to upstream Netdata servers (streaming and database replication).
#### CLABEL
> CLABEL name value source
`CLABEL` defines a label used to organize and identify a chart.
Name and value accept characters according to the following table:
| Character | Symbol | Label Name | Label Value |
|---------------------|:------:|:----------:|:-----------:|
| UTF-8 character | UTF-8 | _ | keep |
| Lower case letter | [a-z] | keep | keep |
| Upper case letter | [A-Z] | keep | [a-z] |
| Digit | [0-9] | keep | keep |
| Underscore | _ | keep | keep |
| Minus | - | keep | keep |
| Plus | + | _ | keep |
| Colon | : | _ | keep |
| Semicolon | ; | _ | : |
| Equal | = | _ | : |
| Period | . | keep | keep |
| Comma | , | . | . |
| Slash | / | keep | keep |
| Backslash | \ | / | / |
| At | @ | _ | keep |
| Space | ' ' | _ | keep |
| Opening parenthesis | ( | _ | keep |
| Closing parenthesis | ) | _ | keep |
| Anything else | | _ | _ |
The `source` is an integer field that can have the following values:
- `1`: The value was set automatically.
- `2`: The value was set manually.
- `4`: This is a K8 label.
- `8`: This is a label defined using `netdata` agent cloud link.
#### CLABEL_COMMIT
`CLABEL_COMMIT` indicates that all labels were defined and the chart can be updated.
#### FUNCTION
> FUNCTION [GLOBAL] "name and parameters of the function" timeout "help string for users"
A function can be used by users to ask for more information from the collector. Netdata maintains a registry of functions in 2 levels:
- per node
- per chart
Both node and chart functions are exactly the same, but chart functions allow Netdata to relate functions with charts and therefore present a context sensitive menu of functions related to the chart the user is using.
A function is identified by a string. The allowed characters in the function definition are:
| Character | Symbol | In Functions |
|-------------------|:------:|:------------:|
| UTF-8 character | UTF-8 | keep |
| Lower case letter | [a-z] | keep |
| Upper case letter | [A-Z] | keep |
| Digit | [0-9] | keep |
| Underscore | _ | keep |
| Comma | , | keep |
| Minus | - | keep |
| Period | . | keep |
| Colon | : | keep |
| Slash | / | keep |
| Space | ' ' | keep |
| Semicolon | ; | : |
| Equal | = | : |
| Backslash | \ | / |
| Anything else | | _ |
Uses can get a list of all the registered functions using the `/api/v1/functions` end point of Netdata.
Users can call functions using the `/api/v1/function` end point of Netdata.
Once a function is called, the plugin will receive at its standard input a command that looks like this:
> FUNCTION transaction_id timeout "name and parameters of the function"
The plugin is expected to parse and validate `name and parameters of the function`. Netdata allows users to edit this string, append more parameters or even change the ones the plugin originally exposed. To minimize the security risk, Netdata guarantees that only the characters shown above are accepted in function definitions, but still the plugin should carefully inspect the `name and parameters of the function` to ensure that it is valid and not harmful.
If the plugin rejects the request, it should respond with this:
```
FUNCTION_RESULT_BEGIN transaction_id 400 application/json
{
"status": 400,
"error_message": "description of the rejection reasons"
}
FUNCTION_RESULT_END
```
If the plugin prepares a response, it should send (via its standard output, together with the collected data, but not interleaved with them):
> FUNCTION_RESULT_BEGIN transaction_id http_error_code content_type expiration
Where:
- `transaction_id` is the transaction id that Netdata sent for this function execution
- `http_error` is the http error code Netdata should respond with, 200 is the "ok" response
- `content_type` is the content type of the response
- `expiration` is the absolute timestamp (number, unix epoch) this response expires
Immediately after this, all text is assumed to be the response content.
The content is text and line oriented. The maximum line length accepted is 15kb. Longer lines will be truncated.
The type of the context itself depends on the plugin and the UI.
To terminate the message, Netdata seeks a line with just this:
> FUNCTION_RESULT_END
This defines the end of the message. `FUNCTION_RESULT_END` should appear in a line alone, without any other text, so it is wise to add `\n` before and after it.
After this line, Netdata resumes processing collected metrics from the plugin.
## Data collection
data collection is defined as a series of `BEGIN` -> `SET` -> `END` lines
> BEGIN type.id [microseconds]
- `type.id`
is the unique identification of the chart (as given in `CHART`)
- `microseconds`
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 transferring
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
- `id`
is the unique identification of the dimension (of the chart just began)
- `value`
is the collected value, only integer values are collected. If you want to push fractional values, multiply this value by 100 or 1000 and set the `DIMENSION` divider to 1000.
> END
END does not take any parameters, it commits the collected values for all dimensions to the chart. If a dimensions was not `SET`, its value will be empty for this commit.
More `SET` lines may appear to update all the dimensions of the chart.
All of them in one `BEGIN` -> `END` block.
All `SET` lines within a single `BEGIN` -> `END` block have to refer to the
same chart.
If more charts need to be updated, each chart should have its own
`BEGIN` -> `SET` -> `END` block.
If, for any reason, a plugin has issued a `BEGIN` but wants to cancel it,
it can issue a `FLUSH`. The `FLUSH` command will in
|