blob: ba44bfbd2a835adeb4931dfd370d95d3c4ecf116 (
plain)
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
|
# agent
This library is a tool for writing [netdata](https://github.com/netdata/netdata) plugins.
We strongly believe that custom plugins are very important, and they must be easy to write.
Definitions:
- orchestrator
> plugin orchestrators are external plugins that do not collect any data by themselves. Instead, they support data collection modules written in the language of the orchestrator. Usually the orchestrator provides a higher level abstraction, making it ideal for writing new data collection modules with the minimum of code.
- plugin
> plugin is a set of data collection modules.
- module
> module is a data collector. It collects, processes and returns processed data to the orchestrator.
- job
> job is a module instance with specific settings.
Package provides:
- CLI parser
- plugin orchestrator (loads configurations, creates and serves jobs)
You are responsible only for __creating modules__.
## Custom plugin example
[Yep! So easy!](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/examples/simple/main.go)
## How to write a Module
Module is responsible for **charts creating** and **data collecting**. Implement Module interface and that is it.
```go
type Module interface {
// Init does initialization.
// If it returns false, the job will be disabled.
Init() bool
// Check is called after Init.
// If it returns false, the job will be disabled.
Check() bool
// Charts returns the chart definition.
// Make sure not to share returned instance.
Charts() *Charts
// Collect collects metrics.
Collect() map[string]int64
// SetLogger sets logger.
SetLogger(l *logger.Logger)
// Cleanup performs cleanup if needed.
Cleanup()
}
// Base is a helper struct. All modules should embed this struct.
type Base struct {
*logger.Logger
}
// SetLogger sets logger.
func (b *Base) SetLogger(l *logger.Logger) { b.Logger = l }
```
## How to write a Plugin
Since plugin is a set of modules all you need is:
- write module(s)
- add module(s) to the plugins [registry](https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/plugin/module/registry.go)
- start the plugin
## How to integrate your plugin into Netdata
Three simple steps:
- move the plugin to the `plugins.d` dir.
- add plugin configuration file to the `etc/netdata/` dir.
- add modules configuration files to the `etc/netdata/<DIR_NAME>/` dir.
Congratulations!
## Configurations
Configurations are written in [YAML](https://yaml.org/).
- plugin configuration:
```yaml
# Enable/disable the whole plugin.
enabled: yes
# Default enable/disable value for all modules.
default_run: yes
# Maximum number of used CPUs. Zero means no limit.
max_procs: 0
# Enable/disable specific plugin module
modules:
# module_name1: yes
# module_name2: yes
```
- module configuration
```yaml
# [ GLOBAL ]
update_every: 1
autodetection_retry: 0
# [ JOBS ]
jobs:
- name: job1
param1: value1
param2: value2
- name: job2
param1: value1
param2: value2
```
Plugin uses `yaml.Unmarshal` to add configuration parameters to the module. Please use `yaml` tags!
## Debug
Plugin CLI:
```
Usage:
plugin [OPTIONS] [update every]
Application Options:
-d, --debug debug mode
-m, --modules= modules name (default: all)
-c, --config= config dir
Help Options:
-h, --help Show this help message
```
Specific module debug:
```
# become user netdata
sudo su -s /bin/bash netdata
# run plugin in debug mode
./<plugin_name> -d -m <module_name>
```
Change `<plugin_name>` to your plugin name and `<module_name>` to the module name you want to debug.
|
