summaryrefslogtreecommitdiffstats
path: root/libnetdata/dyn_conf/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'libnetdata/dyn_conf/README.md')
-rw-r--r--libnetdata/dyn_conf/README.md188
1 files changed, 0 insertions, 188 deletions
diff --git a/libnetdata/dyn_conf/README.md b/libnetdata/dyn_conf/README.md
deleted file mode 100644
index 17d059b02..000000000
--- a/libnetdata/dyn_conf/README.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# 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) |
-
-## Internal Plugins API
-
-TBD
-
-## External Plugins API
-
-### Commands plugins can use
-
-#### DYNCFG_ENABLE
-
-Plugin signifies to agent its ability to use new dynamic config and the name it wishes to use by sending
-
-```
-DYNCFG_ENABLE [{PLUGIN_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).
-
-#### DYNCFG_RESET
-
-Sending this, will reset the internal state of the agent, considering this a `DYNCFG_ENABLE`.
-
-```
-DYNCFG_RESET
-```
-
-
-#### DYNCFG_REGISTER_MODULE
-
-```
-DYNCFG_REGISTER_MODULE {MODULE_NAME} {MODULE_TYPE}
-```
-
-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 a module has been registered agent can call `set_module_config`, `get_module_config` and `get_module_config_schema`.
-
-When `MODULE_TYPE` is `job_array` the agent may also send `set_job_config`, `get_job_config` and `get_job_config_schema`.
-
-#### DYNCFG_REGISTER_JOB
-
-The plugin can use `DYNCFG_REGISTER_JOB` to register its own configuration jobs. It should not register jobs configured
-via DYNCFG (doing so, the agent will shutdown the plugin).
-
-
-```
-DYNCFG_REGISTER_JOB {MODULE_NAME} {JOB_NAME} {JOB_TYPE} {FLAGS}
-```
-
-Where:
-
-- `MODULE_NAME` is the name of the module.
-- `JOB_NAME` is the name of the job.
-- `JOB_TYPE` is either `stock` or `autodiscovered`.
-- `FLAGS`, just send zero.
-
-#### REPORT_JOB_STATUS
-
-```
-REPORT_JOB_STATUS {MODULE_NAME} {JOB_NAME} {STATUS} {STATE} ["REASON"]
-```
-
-Note the REASON parameter is optional and can be entirelly ommited (for example when state is OK there is no need to send any reason).
-
-Where:
-
-- `MODULE_NAME` is the name of the module.
-- `JOB_NAME` is the name of the job.
-- `STATUS` is one of `stopped`, `running`, or `error`.
-- `STATE`, just send zero.
-- `REASON` is a message describing the status. In case you don't want to send any reason string it is preferable to omit this parameter altogether (as opposed to sending empty string `""`).
-
-
-### Commands plugins must serve
-
-Once a plugin calls `DYNCFG_ENABLE`, the must be able to handle these calls.
-
-function|parameters|prerequisites|request payload|response payload|
-:---:|:---:|:---:|:---:|:---:|
-`set_plugin_config`|none|`DYNCFG_ENABLE`|plugin configuration|none|
-`get_plugin_config`|none|`DYNCFG_ENABLE`|none|plugin configuration|
-`get_plugin_config_schema`|none|`DYNCFG_ENABLE`|none|plugin configuration schema|
-`set_module_config`|`module_name`|`DYNCFG_REGISTER_MODULE`|module configuration|none|
-`get_module_config`|`module_name`|`DYNCFG_REGISTER_MODULE`|none|module configuration|
-`get_module_config_schema`|`module_name`|`DYNCFG_REGISTER_MODULE`|none|module configuration schema|
-`set_job_config`|`module_name`, `job_name`|`DYNCFG_REGISTER_MODULE`|job configuration|none|
-`get_job_config`|`module_name`, `job_name`|`DYNCFG_REGISTER_MODULE`|none|job configuration|
-`get_job_config_schema`|`module_name`, `job_name`|`DYNCFG_REGISTER_MODULE`|none|job configuration schema|
-
-All of them work like this:
-
-If the request payload is `none`, then the request looks like this:
-
-```bash
-FUNCTION {TRANSACTION_UUID} {TIMEOUT_SECONDS} "{function} {parameters}"
-```
-
-When there is payload, the request looks like this:
-
-```bash
-FUNCTION_PAYLOAD {TRANSACTION_UUID} {TIMEOUT_SECONDS} "{function} {parameters}"
-<payload>
-FUNCTION_PAYLOAD_END
-```
-
-In all cases, the response is like this:
-
-```bash
-FUNCTION_RESULT_BEGIN {TRANSACTION_UUID} {HTTP_RESPONSE_CODE} "{CONTENT_TYPE}" {EXPIRATION_TIMESTAMP}
-<payload>
-FUNCTION_RESULT_END
-```
-Where:
-- `TRANSACTION_UUID` is the same UUID received with the request.
-- `HTTP_RESPONSE_CODE` is either `0` (rejected) or `1` (accepted).
-- `CONTENT_TYPE` should reflect the `payload` returned.
-- `EXPIRATION_TIMESTAMP` can be zero.
-
-
-## DYNCFG with 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.