9dea17ac2 · cryptotaxi247/netdata-1

@@ -1,20 +1,14 @@

1 -<!--

2 -title: "charts.d.plugin"

3 -custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/charts.d.plugin/README.md"

4 -sidebar_label: "charts.d.plugin"

5 -learn_status: "Published"

6 -learn_topic_type: "Tasks"

7 -learn_rel_path: "Developers/External plugins"

8 --->

9 -

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

14 -1. It runs as an independent process `ps fax` shows it

15 -2. It is started and stopped automatically by Netdata

16 -3. It communicates with Netdata via a unidirectional pipe (sending data to the `netdata` daemon)

17 -4. Supports any number of data collection **modules**

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](https://github.com/netdata/netdata/blob/master/collectors/plugins.d/README.md) prior to reading this page.

11 +

12

13 `charts.d.plugin` has been designed so that the actual script that will do data collection will be permanently in

14 memory, collecting data with as little overheads as possible

@@ -25,12 +19,11 @@ The scripts should have the filename suffix: `.chart.sh`.

19

20 ## Configuration

21

28 -`charts.d.plugin` itself can be configured using the configuration file `/etc/netdata/charts.d.conf`

29 -(to edit it on your system run `/etc/netdata/edit-config charts.d.conf`). This file is also a BASH script.

22 +`charts.d.plugin` itself can be [configured](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#use-edit-config-to-edit-configuration-files) using the configuration file `/etc/netdata/charts.d.conf`. This file is also a BASH script.

23

24 In this file, you can place statements like this:

25

33 -```

26 +```conf

27 enable_all_charts="yes"

28 X="yes"

29 Y="no"

@@ -48,36 +41,31 @@ A `charts.d.plugin` module is a BASH script defining a few functions.

41

42 For a module called `X`, the following criteria must be met:

43

51 -1. The module script must be called `X.chart.sh` and placed in `/usr/libexec/netdata/charts.d`.

44 +1. The module script must be called `X.chart.sh` and placed in `/usr/libexec/netdata/charts.d`.

45

53 -2. If the module needs a configuration, it should be called `X.conf` and placed in `/etc/netdata/charts.d`.

54 - The configuration file `X.conf` is also a BASH script itself.

55 - To edit the default files supplied by Netdata, run `/etc/netdata/edit-config charts.d/X.conf`,

56 - where `X` is the name of the module.

46 +2. If the module needs a configuration, it should be called `X.conf` and placed in `/etc/netdata/charts.d`.

47 + The configuration file `X.conf` is also a BASH script itself.

48 + 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.

49

58 -3. All functions and global variables defined in the script and its configuration, must begin with `X_`.

50 +3. All functions and global variables defined in the script and its configuration, must begin with `X_`.

51

60 -4. The following functions must be defined:

52 +4. The following functions must be defined:

53

62 - - `X_check()` - returns 0 or 1 depending on whether the module is able to run or not

54 + - `X_check()` - returns 0 or 1 depending on whether the module is able to run or not

55 (following the standard Linux command line return codes: 0 = OK, the collector can operate and 1 = FAILED,

56 the collector cannot be used).

57

66 - - `X_create()` - creates the Netdata charts, following the standard Netdata plugin guides as described in

67 - **[External Plugins](https://github.com/netdata/netdata/blob/master/collectors/plugins.d/README.md)** (commands `CHART` and `DIMENSION`).

58 + - `X_create()` - creates the Netdata charts (commands `CHART` and `DIMENSION`).

59 The return value does matter: 0 = OK, 1 = FAILED.

60

70 - - `X_update()` - collects the values for the defined charts, following the standard Netdata plugin guides

71 - as described in **[External Plugins](https://github.com/netdata/netdata/blob/master/collectors/plugins.d/README.md)** (commands `BEGIN`, `SET`, `END`).

61 + - `X_update()` - collects the values for the defined charts (commands `BEGIN`, `SET`, `END`).

62 The return value also matters: 0 = OK, 1 = FAILED.

63

74 -5. The following global variables are available to be set:

75 - - `X_update_every` - is the data collection frequency for the module script, in seconds.

64 +5. The following global variables are available to be set:

65 + - `X_update_every` - is the data collection frequency for the module script, in seconds.

66

67 The module script may use more functions or variables. But all of them must begin with `X_`.

68

79 -The standard Netdata plugin variables are also available (check **[External Plugins](https://github.com/netdata/netdata/blob/master/collectors/plugins.d/README.md)**).

80 -

69 ### X_check()

70

71 The purpose of the BASH function `X_check()` is to check if the module can collect data (or check its config).

@@ -90,7 +78,7 @@ connect to a local mysql database to find out if it can read the values it needs

78 ### X_create()

79

80 The purpose of the BASH function `X_create()` is to create the charts and dimensions using the standard Netdata

93 -plugin guides (**[External Plugins](https://github.com/netdata/netdata/blob/master/collectors/plugins.d/README.md)**).

81 +plugin guidelines.

82

83 `X_create()` will be called just once and only after `X_check()` was successful.

84 You can however call it yourself when there is need for it (for example to add a new dimension to an existing chart).

@@ -100,7 +88,7 @@ A non-zero return value will disable the collector.

88 ### X_update()

89

90 `X_update()` will be called repeatedly every `X_update_every` seconds, to collect new values and send them to Netdata,

103 -following the Netdata plugin guides (**[External Plugins](https://github.com/netdata/netdata/blob/master/collectors/plugins.d/README.md)**).

91 +following the Netdata plugin guidelines.

92

93 The function will be called with one parameter: microseconds since the last time it was run. This value should be

94 appended to the `BEGIN` statement of every chart updated by the collector script.

@@ -187,16 +175,14 @@ You can have multiple `charts.d.plugin` running to overcome this problem.

175

176 This is what you need to do:

177

190 -1. Decide a new name for the new charts.d instance: example `charts2.d`.

178 +1. Decide a new name for the new charts.d instance: example `charts2.d`.

179

192 -2. Create/edit the files `/etc/netdata/charts.d.conf` and `/etc/netdata/charts2.d.conf` and enable / disable the

180 +2. Create/edit the files `/etc/netdata/charts.d.conf` and `/etc/netdata/charts2.d.conf` and enable / disable the

181 module you want each to run. Remember to set `enable_all_charts="no"` to both of them, and enable the individual

182 modules for each.

183

196 -3. link `/usr/libexec/netdata/plugins.d/charts.d.plugin` to `/usr/libexec/netdata/plugins.d/charts2.d.plugin`.

184 +3. link `/usr/libexec/netdata/plugins.d/charts.d.plugin` to `/usr/libexec/netdata/plugins.d/charts2.d.plugin`.

185 Netdata will spawn a new charts.d process.

186

187 Execute the above in this order, since Netdata will (by default) attempt to start new plugins soon after they are

188 created in `/usr/libexec/netdata/plugins.d/`.

201 -

202 -

Fix/introduce links inside charts.d.plugin documentation (#14884)