diff options
Diffstat (limited to 'plugins.d/README.md')
| -rw-r--r-- | plugins.d/README.md | 236 |
1 files changed, 0 insertions, 236 deletions
diff --git a/plugins.d/README.md b/plugins.d/README.md deleted file mode 100644 index 35b9a2d99..000000000 --- a/plugins.d/README.md +++ /dev/null @@ -1,236 +0,0 @@ -netdata plugins -=============== - -Any program that can print a few values to its standard output can become -a netdata plugin. - -There are 5 lines netdata parses. lines starting with: - -- `CHART` - create a new chart -- `DIMENSION` - add a dimension to the chart just created -- `BEGIN` - initialize data collection for a chart -- `SET` - set the value of a dimension for the initialized chart -- `END` - complete data collection for the initialized chart - -a single program can produce any number of charts with any number of dimensions -each. - -charts can also be added any time (not just the beginning). - -### command line parameters - -The plugin should accept just **one** parameter: **the number of seconds it is -expected to update the values for its charts**. The value passed by netdata -to the plugin is controlled via its configuration file (so there is not need -for the plugin to handle this configuration option). - -The script can overwrite the update frequency. For example, the server may -request per second updates, but the script may overwrite this to one update -every 5 seconds. - -### environment variables - -There are a few environment variables that are set by `netdata` and are -available for the plugin to use. - -variable|description -:------:|:---------- -`NETDATA_CONFIG_DIR`|The directory where all netdata related configuration should be stored. If the plugin requires custom configuration, this is the place to save it. -`NETDATA_PLUGINS_DIR`|The directory where all netdata plugins are stored. -`NETDATA_WEB_DIR`|The directory where the web files of netdata are saved. -`NETDATA_CACHE_DIR`|The directory where the cache files of netdata are stored. Use this directory if the plugin requires a place to store data. A new directory should be created for the plugin for this purpose, inside this directory. -`NETDATA_LOG_DIR`|The directory where the log files are stored. By default the `stderr` output of the plugin will be saved in the `error.log` file of netdata. -`NETDATA_HOST_PREFIX`|This is used in environments where system directories like `/sys` and `/proc` have to be accessed at a different path. -`NETDATA_DEBUG_FLAGS`|This is number (probably in hex starting with `0x`), that enables certain netdata debugging features. -`NETDATA_UPDATE_EVERY`|The minimum number of seconds between chart refreshes. This is like the **internal clock** of netdata (it is user configurable, defaulting to `1`). There is no meaning for a plugin to update its values more frequently than this number of seconds. - - -# the output of the plugin - -The plugin should output instructions for netdata to its output (`stdout`). - -## CHART - -`CHART` defines a new chart. - -the template is: - -> CHART type.id name title units [family [category [charttype [priority [update_every]]]]] - - where: - - `type.id` - - uniquely identifies the chart, - this is what will be needed to add values to the chart - - - `name` - - is the name that will be presented to the used for this chart - - - `title` - - the text above the chart - - - `units` - - the label of the vertical axis of the chart, - all dimensions added to a chart should have the same units - of measurement - - - `family` - - is used to group charts together - (for example all eth0 charts should say: eth0), - if empty or missing, the `id` part of `type.id` will be used - - - `category` - - the section under which the chart will appear - (for example mem.ram should appear in the 'system' section), - the special word 'none' means: do not show this chart on the home page, - if empty or missing, the `type` part of `type.id` will be used - - - `charttype` - - one of `line`, `area` or `stacked`, - if empty or missing, the `line` will be used - - - `priority` - - is the relative priority of the charts as rendered on the web page, - lower numbers make the charts appear before the ones with higher numbers, - if empty or missing, `1000` will be used - - - `update_every` - - overwrite the update frequency set by the server, - if empty or missing, the user configured value will be used - - -## DIMENSION - -`DIMENSION` defines a new dimension for the chart - -the template is: - -> DIMENSION id [name [algorithm [multiplier [divisor [hidden]]]]] - - where: - - - `id` - - the `id` of this dimension (it is a text value, not numeric), - this will be needed later to add values to the dimension - - - `name` - - the name of the dimension as it will appear at the legend of the chart, - if empty or missing the `id` will be used - - - `algorithm` - - one of: - - * `absolute` - - the value is to drawn as-is (interpolated to second boundary), - if `algorithm` is empty, invalid or missing, `absolute` is used - - * `incremental` - - the value increases over time, - the difference from the last value is presented in the chart, - the server interpolates the value and calculates a per second figure - - * `percentage-of-absolute-row` - - the % of this value compared to the total of all dimensions - - * `percentage-of-incremental-row` - - the % of this value compared to the incremental total of - all dimensions - - - `multiplier` - - an integer value to multiply the collected value, - if empty or missing, `1` is used - - - `divisor` - - an integer value to divide the collected value, - if empty or missing, `1` is used - - - `hidden` - - giving the keyword `hidden` will make this dimension hidden, - it will take part in the calculations but will not be presented in the chart - - -## data collection - -data collection is defined as a series of `BEGIN` -> `SET` -> `END` lines - -> BEGIN type.id [microseconds] - - - `type.id` - - is the unique identification of the chart (as given in `CHART`) - - - `microseconds` - - is the number of microseconds since the last update of the chart, - it is optional. - - Under heavy system load, the system may have some latency transfering - data from the plugins to netdata via the pipe. This number improves - accuracy significantly, since the plugin is able to calculate the - duration between its iterations better than netdata. - - The first time the plugin is started, no microseconds should be given - to netdata. - -> SET id = value - - - `id` - - is the unique identification of the dimension (of the chart just began) - - - `value` - - is the collected value - -> END - - END does not take any parameters, it commits the collected values to the chart. - -More `SET` lines may appear to update all the dimensions of the chart. -All of them in one `BEGIN` -> `END` block. - -All `SET` lines within a single `BEGIN` -> `END` block have to refer to the -same chart. - -If more charts need to be updated, each chart should have its own -`BEGIN` -> `SET` -> `END` block. - -If, for any reason, a plugin has issued a `BEGIN` but wants to cancel it, -it can issue a `FLUSH`. The `FLUSH` command will instruct netdata to ignore -the last `BEGIN` command. - -If a plugin does not behave properly (outputs invalid lines, or does not -follow these guidelines), will be disabled by netdata. - - -### collected values - -netdata will collect any **signed** value in the 64bit range: -`-9.223.372.036.854.775.808` to `+9.223.372.036.854.775.807` - -Internally, all calculations are made using 128 bit double precision and are -stored in 30 bits as floating point. - -If a value is not collected, leave it empty, like this: - -`SET id = ` - -or do not output the line at all. |