blob: 6c8127400e33a36437b96d56e8a0cf74b9efcaab (
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
158
159
160
161
162
163
164
165
166
167
|
# Netdata Dynamic Configuration
Purpose of Netdata Dynamic Configuration is to allow configuration of select Netdata plugins and options through the
Netdata API and by extension by UI.
## HTTP API documentation
### Summary API
For summary of all jobs and their statuses (for all children that stream to parent) use the following URL:
| Method | Endpoint | Description |
|:-------:|-------------------------------|------------------------------------------------------------|
| **GET** | `api/v2/job_statuses` | list of Jobs |
| **GET** | `api/v2/job_statuses?grouped` | list of Jobs (hierarchical, grouped by host/plugin/module) |
### Dyncfg API
### Top level
| Method | Endpoint | Description |
|:-------:|------------------|-----------------------------------------|
| **GET** | `/api/v2/config` | registered Plugins (sent DYNCFG_ENABLE) |
### Plugin level
| Method | Endpoint | Description |
|:-------:|-----------------------------------|------------------------------|
| **GET** | `/api/v2/config/[plugin]` | Plugin config |
| **PUT** | `/api/v2/config/[plugin]` | update Plugin config |
| **GET** | `/api/v2/config/[plugin]/modules` | Modules registered by Plugin |
| **GET** | `/api/v2/config/[plugin]/schema` | Plugin config schema |
### Module level
| Method | Endpoint | Description |
|:-------:|-----------------------------------------------|---------------------------|
| **GET** | `/api/v2/config/<plugin>/[module]` | Module config |
| **PUT** | `/api/v2/config/[plugin]/[module]` | update Module config |
| **GET** | `/api/v2/config/[plugin]/[module]/jobs` | Jobs registered by Module |
| **GET** | `/api/v2/config/[plugin]/[module]/job_schema` | Job config schema |
| **GET** | `/api/v2/config/[plugin]/[module]/schema` | Module config schema |
### Job level - only for modules where `module_type == job_array`
| Method | Endpoint | Description |
|:----------:|------------------------------------------|--------------------------------|
| **GET** | `/api/v2/config/[plugin]/[module]/[job]` | Job config |
| **PUT** | `/api/v2/config/[plugin]/[module]/[job]` | update Job config |
| **POST** | `/api/v2/config/[plugin]/[module]/[job]` | create Job |
| **DELETE** | `/api/v2/config/[plugin]/[module]/[job]` | delete Job (created by Dyncfg) |
## AGENT<->PLUGIN interface documentation
### 1. DYNCFG_ENABLE
Plugin signifies to agent its ability to use new dynamic config and the name it wishes to use by sending
```
plugin->agent:
=============
DYNCFG_ENABLE [plugin_url_name]
```
This can be sent only once per lifetime of the plugin (at startup or later) sending it multiple times is considered a
protocol violation and plugin might get terminated.
After this command is sent the plugin has to be ready to accept all the new commands/keywords related to dynamic
configuration (this command lets agent know this plugin is dyncfg capable and wishes to use dyncfg functionality).
After this command agent can call
```
agent->plugin:
=============
FUNCTION_PAYLOAD [UUID] 1 "set_plugin_config"
the new configuration
blah blah blah
FUNCTION_PAYLOAD_END
plugin->agent:
=============
FUNCTION_RESULT_BEGIN [UUID] [(1/0)(accept/reject)] [text/plain] 5
FUNCTION_RESULT_END
```
to set the new config which can be accepted/rejected by plugin by sending answer for this FUNCTION as it would with any
other regular function.
The new `FUNCTION_PAYLOAD` command differs from regular `FUNCTION` command exclusively in its ability to send bigger
payloads (configuration file contents) to the plugin (not just parameters list).
Agent can also call (after `DYNCFG_ENABLE`)
```
Agent->plugin:
=============
FUNCTION [UID] 1 "get_plugin_config"
Plugin->agent:
=============
FUNCTION_RESULT_BEGIN [UID] 1 text/plain 5
{
"the currently used config from plugin" : "nice"
}
FUNCTION_RESULT_END
```
and
```
Agent->plugin:
=============
FUNCTION [UID] 1 "get_plugin_config_schema"
Plugin->agent:
=============
FUNCTION_RESULT_BEGIN [UID] 1 text/plain 5
{
"the schema of plugin configuration" : "splendid"
}
FUNCTION_RESULT_END
```
Plugin can also register zero, one or more configurable modules using:
```
plugin->agent:
=============
DYNCFG_REGISTER_MODULE [module_url_name] (job_array|single)
```
modules can be added any time during plugins lifetime (you are not required to add them all at startup).
### 2. DYNCFG_REGISTER_MODULE
Module has to choose one of following types at registration:
- `single` - module itself has configuration but does not accept any jobs *(this is useful mainly for internal netdata
configurable things like webserver etc.)*
- `job_array` - module itself **can** *(not must)* have configuration and it has an array of jobs which can be added,
modified and deleted. **this is what plugin developer needs in most cases**
After module has been registered agent can call
- `set_module_config [module]` FUNCTION_PAYLOAD
- `get_module_config [module]` FUNCTION
- `get_module_config_schema [module]` FUNCTION
with same syntax as `set_plugin_config` and `get_plugin_config`. In case of `set` command the plugin has ability to
reject the new configuration pushed to it.
In a case the module was registered as `job_array` type following commands can be used to manage jobs:
### 3. Job interface for job_array modules
- `get_job_config_schema [module]` - FUNCTION
- `get_job_config [module] [job]` - FUNCTION
- `set_job_config [module] [job]` - FUNCTION_PAYLOAD
- `delete_job_name [module] [job]` - FUNCTION
### 4. Streaming
When above commands are transferred trough streaming additionally `plugin_name` is prefixed as first parameter. This is
done to allow routing to appropriate plugin @child.
As a plugin developer you don't need to concern yourself with this detail as that parameter is stripped when sent to the
plugin *(and added when sent trough streaming)* automagically.
|
