netdata/libnetdata/dyn_conf/README.md

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:

FUNCTION {TRANSACTION_UUID} {TIMEOUT_SECONDS} "{function} {parameters}"  

When there is payload, the request looks like this:

FUNCTION_PAYLOAD {TRANSACTION_UUID} {TIMEOUT_SECONDS} "{function} {parameters}" 
<payload>
FUNCTION_PAYLOAD_END  

In all cases, the response is like this:

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.