@cryptotaxi247 / netdata-1
Code Commits Issues Pulls Sessions CI/CD
master
master
md 189 lines 7.2 KB
Rendered Raw
1 # charts.d.plugin
2
3 `charts.d.plugin` is a Netdata external plugin. It is an **orchestrator** for data collection modules written in `BASH` v4+.
4
5 1. It runs as an independent process `ps fax` shows it
6 2. It is started and stopped automatically by Netdata
7 3. It communicates with Netdata via a unidirectional pipe (sending data to the `netdata` daemon)
8 4. Supports any number of data collection **modules**
9
10 To better understand the guidelines and the API behind our External plugins, please have a look at the [Introduction to External plugins](/src/plugins.d/README.md) prior to reading this page.
11
12 `charts.d.plugin` has been designed so that the actual script that will do data collection will be permanently in
13 memory, collecting data with as little overheads as possible
14 (i.e. initialize once, repeatedly collect values with minimal overhead).
15
16 `charts.d.plugin` looks for scripts in `/usr/lib/netdata/charts.d`.
17 The scripts should have the filename suffix: `.chart.sh`.
18
19 By default, `charts.d.plugin` is not included as part of the install when using [our official native DEB/RPM packages](/packaging/installer/methods/packages.md). You can install it by installing the `netdata-plugin-chartsd` package.
20
21 ## Configuration
22
23 `charts.d.plugin` itself can be [configured](/docs/netdata-agent/configuration/README.md#edit-configuration-files) using the configuration file `/etc/netdata/charts.d.conf`. This file is also a BASH script.
24
25 In this file, you can place statements like this:
26
27 ```text
28 enable_all_charts="yes"
29 X="yes"
30 Y="no"
31 ```
32
33 where `X` and `Y` are the names of individual charts.d collector scripts.
34 When set to `yes`, charts.d will evaluate the collector script (see below).
35 When set to `no`, charts.d will ignore the collector script.
36
37 The variable `enable_all_charts` sets the default enable/disable state for all charts.
38
39 ## A charts.d module
40
41 A `charts.d.plugin` module is a BASH script defining a few functions.
42
43 For a module called `X`, the following criteria must be met:
44
45 1. The module script must be called `X.chart.sh` and placed in `/usr/libexec/netdata/charts.d`.
46
47 2. If the module needs a configuration, it should be called `X.conf` and placed in `/etc/netdata/charts.d`.
48 The configuration file `X.conf` is also a BASH script itself.
49 You can edit the default files supplied by Netdata, by editing `/etc/netdata/edit-config charts.d/X.conf`, where `X` is the name of the module.
50
51 3. All functions and global variables defined in the script and its configuration, must begin with `X_`.
52
53 4. The following functions must be defined:
54
55 - `X_check()` - returns 0 or 1 depending on whether the module is able to run or not
56 (following the standard Linux command line return codes: 0 = OK, the collector can operate and 1 = FAILED,
57 the collector cannot be used).
58
59 - `X_create()` - creates the Netdata charts (commands `CHART` and `DIMENSION`).
60 The return value does matter: 0 = OK, 1 = FAILED.
61
62 - `X_update()` - collects the values for the defined charts (commands `BEGIN`, `SET`, `END`).
63 The return value also matters: 0 = OK, 1 = FAILED.
64
65 5. The following global variables are available to be set:
66 - `X_update_every` - is the data collection frequency for the module script, in seconds.
67
68 The module script may use more functions or variables. But all of them must begin with `X_`.
69
70 ### X_check()
71
72 The purpose of the BASH function `X_check()` is to check if the module can collect data (or check its config).
73
74 For example, if the module is about monitoring a local mysql database, the `X_check()` function may attempt to
75 connect to a local mysql database to find out if it can read the values it needs.
76
77 `X_check()` is run only once for the lifetime of the module.
78
79 ### X_create()
80
81 The purpose of the BASH function `X_create()` is to create the charts and dimensions using the standard Netdata
82 plugin guidelines.
83
84 `X_create()` will be called just once and only after `X_check()` was successful.
85 You can however call it yourself when there is need for it (for example to add a new dimension to an existing chart).
86
87 A non-zero return value will disable the collector.
88
89 ### X_update()
90
91 `X_update()` will be called repeatedly every `X_update_every` seconds, to collect new values and send them to Netdata,
92 following the Netdata plugin guidelines.
93
94 The function will be called with one parameter: microseconds since the last time it was run. This value should be
95 appended to the `BEGIN` statement of every chart updated by the collector script.
96
97 A non-zero return value will disable the collector.
98
99 ### Useful functions charts.d provides
100
101 Module scripts can use the following charts.d functions:
102
103 #### require_cmd command
104
105 `require_cmd()` will check if a command is available in the running system.
106
107 For example, your `X_check()` function may use it like this:
108
109 ```sh
110 mysql_check() {
111 require_cmd mysql || return 1
112 return 0
113 }
114 ```
115
116 Using the above, if the command `mysql` is not available in the system, the `mysql` module will be disabled.
117
118 #### fixid "string"
119
120 `fixid()` will get a string and return a properly formatted id for a chart or dimension.
121
122 This is an expensive function that should not be used in `X_update()`.
123 You can keep the generated id in a BASH associative array to have the values available in `X_update()`, like this:
124
125 ```sh
126 declare -A X_ids=()
127 X_create() {
128 local name="a very bad name for id"
129
130 X_ids[$name]="$(fixid "$name")"
131 }
132
133 X_update() {
134 local microseconds="$1"
135
136 ...
137 local name="a very bad name for id"
138 ...
139
140 echo "BEGIN ${X_ids[$name]} $microseconds"
141 ...
142 }
143 ```
144
145 ### Debugging your collectors
146
147 You can run `charts.d.plugin` by hand with something like this:
148
149 ```sh
150 # become user netdata
151 sudo su -s /bin/sh netdata
152
153 # run the plugin in debug mode
154 /usr/libexec/netdata/plugins.d/charts.d.plugin debug 1 X Y Z
155 ```
156
157 Charts.d will run in `debug` mode, with an update frequency of `1`, evaluating only the collector scripts
158 `X`, `Y` and `Z`. You can define zero or more module scripts. If none is defined, charts.d will evaluate all
159 module scripts available.
160
161 Keep in mind that if your configs are not in `/etc/netdata`, you should do the following before running
162 `charts.d.plugin`:
163
164 ```sh
165 export NETDATA_USER_CONFIG_DIR="/path/to/etc/netdata"
166 ```
167
168 Also, remember that Netdata runs `chart.d.plugin` as user `netdata` (or any other user the `netdata` process is configured to run as).
169
170 ## Running multiple instances of charts.d.plugin
171
172 `charts.d.plugin` will call the `X_update()` function one after another. This means that a delay in collector `X`
173 will also delay the collection of `Y` and `Z`.
174
175 You can have multiple `charts.d.plugin` running to overcome this problem.
176
177 This is what you need to do:
178
179 1. Decide a new name for the new charts.d instance: example `charts2.d`.
180
181 2. Create/edit the files `/etc/netdata/charts.d.conf` and `/etc/netdata/charts2.d.conf` and enable / disable the
182 module you want each to run. Remember to set `enable_all_charts="no"` to both of them, and enable the individual
183 modules for each.
184
185 3. link `/usr/libexec/netdata/plugins.d/charts.d.plugin` to `/usr/libexec/netdata/plugins.d/charts2.d.plugin`.
186 Netdata will spawn a new charts.d process.
187
188 Execute the above in this order, since Netdata will (by default) attempt to start new plugins soon after they are
189 created in `/usr/libexec/netdata/plugins.d/`.