diff options
author | Joel Hans <joel@netdata.cloud> | 2019-08-13 08:07:17 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-08-13 08:07:17 -0700 |
commit | a726c905bde122d6a03da9866efb51a2e3b526c2 (patch) | |
tree | 7715d332b0eeedbf4e45ea60c698a25c2c30929d /collectors/plugins.d | |
parent | dc38b1d15df2d07f65c0f3c8f8f944fbcc89a574 (diff) |
Change "netdata" to "Netdata" in all docs (#6621)
* First pass of changing netdata to Netdata
* Second pass of netdata -> Netdata
* Starting work on netdata with no whitespace after
* Pass for netdata with no whitespace at the end
* Pass for netdata with no whitespace at the front
Diffstat (limited to 'collectors/plugins.d')
-rw-r--r-- | collectors/plugins.d/README.md | 90 |
1 files changed, 45 insertions, 45 deletions
diff --git a/collectors/plugins.d/README.md b/collectors/plugins.d/README.md index 9134d5163a..d48b424141 100644 --- a/collectors/plugins.d/README.md +++ b/collectors/plugins.d/README.md @@ -1,7 +1,7 @@ # External plugins overview -`plugins.d` is the netdata internal plugin that collects metrics -from external processes, thus allowing netdata to use **external plugins**. +`plugins.d` is the Netdata internal plugin that collects metrics +from external processes, thus allowing Netdata to use **external plugins**. ## Provided External Plugins @@ -19,19 +19,19 @@ plugin|language|O/S|description [node.d.plugin](../node.d.plugin/)|`node.js`|all|a **plugin orchestrator** for data collection modules written in `node.js`. [python.d.plugin](../python.d.plugin/)|`python`|all|a **plugin orchestrator** for data collection modules written in `python` v2 or v3 (both are supported). -Plugin orchestrators may also be described as **modular plugins**. They are modular since they accept custom made modules to be included. Writing modules for these plugins is easier than accessing the native netdata API directly. You will find modules already available for each orchestrator under the directory of the particular modular plugin (e.g. under python.d.plugin for the python orchestrator). +Plugin orchestrators may also be described as **modular plugins**. They are modular since they accept custom made modules to be included. Writing modules for these plugins is easier than accessing the native Netdata API directly. You will find modules already available for each orchestrator under the directory of the particular modular plugin (e.g. under python.d.plugin for the python orchestrator). Each of these modular plugins has each own methods for defining modules. Please check the examples and their documentation. ## Motivation -This plugin allows netdata to use **external plugins** for data collection: +This plugin allows Netdata to use **external plugins** for data collection: 1. external data collection plugins may be written in any computer language. 2. external data collection plugins may use O/S capabilities or `setuid` to - run with escalated privileges (compared to the netdata daemon). - The communication between the external plugin and netdata is unidirectional - (from the plugin to netdata), so that netdata cannot manipulate an external + run with escalated privileges (compared to the `netdata` daemon). + The communication between the external plugin and Netdata is unidirectional + (from the plugin to Netdata), so that Netdata cannot manipulate an external plugin running with escalated privileges. ## Operation @@ -39,23 +39,23 @@ This plugin allows netdata to use **external plugins** for data collection: Each of the external plugins is expected to run forever. Netdata will start it when it starts and stop it when it exits. -If the external plugin exits or crashes, netdata will log an error. -If the external plugin exits or crashes without pushing metrics to netdata, netdata will not start it again. +If the external plugin exits or crashes, Netdata will log an error. +If the external plugin exits or crashes without pushing metrics to Netdata, Netdata will not start it again. - Plugins that exit with any value other than zero, will be disabled. Plugins that exit with zero, will be restarted after some time. -- Plugins may also be disabled by netdata if they output things that netdata does not understand. +- Plugins may also be disabled by Netdata if they output things that Netdata does not understand. -The `stdout` of external plugins is connected to netdata to receive metrics, +The `stdout` of external plugins is connected to Netdata to receive metrics, with the API defined below. -The `stderr` of external plugins is connected to netdata `error.log`. +The `stderr` of external plugins is connected to Netdata's `error.log`. Plugins can create any number of charts with any number of dimensions each. Each chart can have its own characteristics independently of the others generated by the same plugin. For example, one chart may have an update frequency of 1 second, another may have 5 seconds and a third may have 10 seconds. ## Configuration -Netdata will supply the environment variables `NETDATA_USER_CONFIG_DIR` (for user supplied) and `NETDATA_STOCK_CONFIG_DIR` (for netdata supplied) configuration files to identify the directory where configuration files are stored. It is up to the plugin to read the configuration it needs. +Netdata will supply the environment variables `NETDATA_USER_CONFIG_DIR` (for user supplied) and `NETDATA_STOCK_CONFIG_DIR` (for Netdata supplied) configuration files to identify the directory where configuration files are stored. It is up to the plugin to read the configuration it needs. -The `netdata.conf` section [plugins] section contains a list of all the plugins found at the system where netdata runs, with a boolean setting to enable them or not. +The `netdata.conf` section [plugins] section contains a list of all the plugins found at the system where Netdata runs, with a boolean setting to enable them or not. Example: @@ -100,19 +100,19 @@ Netdata will call the plugin with just one command line parameter: the number of Other than the above, the plugin configuration is up to the plugin. -Keep in mind, that the user may use netdata configuration to overwrite chart and dimension parameters. This is transparent to the plugin. +Keep in mind, that the user may use Netdata configuration to overwrite chart and dimension parameters. This is transparent to the plugin. ### Autoconfiguration Plugins should attempt to autoconfigure themselves when possible. -For example, if your plugin wants to monitor `squid`, you can search for it on port `3128` or `8080`. If any succeeds, you can proceed. If it fails you can output an error (on stderr) saying that you cannot find `squid` running and giving instructions about the plugin configuration. Then you can stop (exit with non-zero value), so that netdata will not attempt to start the plugin again. +For example, if your plugin wants to monitor `squid`, you can search for it on port `3128` or `8080`. If any succeeds, you can proceed. If it fails you can output an error (on stderr) saying that you cannot find `squid` running and giving instructions about the plugin configuration. Then you can stop (exit with non-zero value), so that Netdata will not attempt to start the plugin again. ## External Plugins API -Any program that can print a few values to its standard output can become a netdata external plugin. +Any program that can print a few values to its standard output can become a Netdata external plugin. -There are 7 lines netdata parses. lines starting with: +Netdata parses 7 lines starting with: - `CHART` - create or update a chart - `DIMENSION` - add or update a dimension to the chart just created @@ -129,7 +129,7 @@ Charts can be added any time (not just the beginning). ### command line parameters The plugin **MUST** accept just **one** parameter: **the number of seconds it is -expected to update the values for its charts**. The value passed by netdata +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 no need for the plugin to handle this configuration option). @@ -144,24 +144,24 @@ available for the plugin to use. variable|description :------:|:---------- -`NETDATA_USER_CONFIG_DIR`|The directory where all netdata related user configuration should be stored. If the plugin requires custom user configuration, this is the place the user has saved it (normally under `/etc/netdata`). -`NETDATA_STOCK_CONFIG_DIR`|The directory where all netdata related stock configuration should be stored. If the plugin is shipped with configuration files, this is the place they can be found (normally under `/usr/lib/netdata/conf.d`). -`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_USER_CONFIG_DIR`|The directory where all Netdata-related user configuration should be stored. If the plugin requires custom user configuration, this is the place the user has saved it (normally under `/etc/netdata`). +`NETDATA_STOCK_CONFIG_DIR`|The directory where all Netdata -related stock configuration should be stored. If the plugin is shipped with configuration files, this is the place they can be found (normally under `/usr/lib/netdata/conf.d`). +`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 a number (probably in hex starting with `0x`), that enables certain netdata debugging features. Check **[[Tracing Options]]** for more information. -`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. +`NETDATA_DEBUG_FLAGS`|This is a number (probably in hex starting with `0x`), that enables certain Netdata debugging features. Check **[[Tracing Options]]** for more information. +`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`). Since this uses pipes, please make sure you flush stdout after every iteration. +The plugin should output instructions for Netdata to its output (`stdout`). Since this uses pipes, please make sure you flush stdout after every iteration. #### DISABLE -`DISABLE` will disable this plugin. This will prevent netdata from restarting the plugin. You can also exit with the value `1` to have the same effect. +`DISABLE` will disable this plugin. This will prevent Netdata from restarting the plugin. You can also exit with the value `1` to have the same effect. #### CHART @@ -225,11 +225,11 @@ the template is: - `options` - a space separated list of options, enclosed in quotes. 4 options are currently supported: `obsolete` to mark a chart as obsolete (netdata will hide it and delete it after some time), `detail` to mark a chart as insignificant (this may be used by dashboards to make the charts smaller, or somehow visualize properly a less important chart), `store_first` to make netdata store the first collected value, assuming there was an invisible previous value set to zero (this is used by statsd charts - if the first data collected value of incremental dimensions is not zero based, unrealistic spikes will appear with this option set) and `hidden` to perform all operations on a chart, but do not offer it on dashboards (the chart will be send to backends). `CHART` options have been added in netdata v1.7 and the `hidden` option was added in 1.10. + a space separated list of options, enclosed in quotes. 4 options are currently supported: `obsolete` to mark a chart as obsolete (Netdata will hide it and delete it after some time), `detail` to mark a chart as insignificant (this may be used by dashboards to make the charts smaller, or somehow visualize properly a less important chart), `store_first` to make Netdata store the first collected value, assuming there was an invisible previous value set to zero (this is used by statsd charts - if the first data collected value of incremental dimensions is not zero based, unrealistic spikes will appear with this option set) and `hidden` to perform all operations on a chart, but do not offer it on dashboards (the chart will be send to backends). `CHART` options have been added in Netdata v1.7 and the `hidden` option was added in 1.10. - `plugin` and `module` - both are just names that are used to let the user identify the plugin and the module that generated the chart. If `plugin` is unset or empty, netdata will automatically set the filename of the plugin that generated the chart. `module` has not default. + both are just names that are used to let the user identify the plugin and the module that generated the chart. If `plugin` is unset or empty, Netdata will automatically set the filename of the plugin that generated the chart. `module` has not default. #### DIMENSION @@ -290,7 +290,7 @@ the template is: - `options` - a space separated list of options, enclosed in quotes. Options supported: `obsolete` to mark a dimension as obsolete (netdata will delete it after some time) and `hidden` to make this dimension hidden, it will take part in the calculations but will not be presented in the chart. + a space separated list of options, enclosed in quotes. Options supported: `obsolete` to mark a dimension as obsolete (Netdata will delete it after some time) and `hidden` to make this dimension hidden, it will take part in the calculations but will not be presented in the chart. #### VARIABLE @@ -302,7 +302,7 @@ the template is: Variables support 2 scopes: - `GLOBAL` or `HOST` to define the variable at the host level. -- `LOCAL` or `CHART` to define the variable at the chart level. Use chart-local variables when the same variable may exist for different charts (i.e. netdata monitors 2 mysql servers, and you need to set the `max_connections` each server accepts). Using chart-local variables is the ideal to build alarm templates. +- `LOCAL` or `CHART` to define the variable at the chart level. Use chart-local variables when the same variable may exist for different charts (i.e. Netdata monitors 2 mysql servers, and you need to set the `max_connections` each server accepts). Using chart-local variables is the ideal to build alarm templates. The position of the `VARIABLE` line, sets its default scope (in case you do not specify a scope). So, defining a `VARIABLE` before any `CHART`, or between `END` and `BEGIN` (outside any chart), sets `GLOBAL` scope, while defining a `VARIABLE` just after a `CHART` or a `DIMENSION`, or within the `BEGIN` - `END` block of a chart, sets `LOCAL` scope. @@ -310,9 +310,9 @@ These variables can be set and updated at any point. Variable names should use alphanumeric characters, the `.` and the `_`. -The `value` is floating point (netdata used `long double`). +The `value` is floating point (Netdata used `long double`). -Variables are transferred to upstream netdata servers (streaming and database replication). +Variables are transferred to upstream Netdata servers (streaming and database replication). ## Data collection @@ -329,12 +329,12 @@ data collection is defined as a series of `BEGIN` -> `SET` -> `END` lines 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 transferring - data from the plugins to netdata via the pipe. This number improves + 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. + duration between its iterations better than Netdata. The first time the plugin is started, no microseconds should be given - to netdata. + to Netdata. > SET id = value @@ -360,15 +360,15 @@ 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 +it can issue a `FLUSH`. The `FLUSH` command will instruct Netdata to ignore all the values collected since 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. +follow these guidelines), will be disabled by Netdata. ### collected values -netdata will collect any **signed** value in the 64bit range: +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` If a value is not collected, leave it empty, like this: @@ -381,7 +381,7 @@ or do not output the line at all. 1. **python**, use `python.d.plugin`, there are many examples in the [python.d directory](../python.d.plugin/) - python is ideal for netdata plugins. It is a simple, yet powerful way to collect data, it has a very small memory footprint, although it is not the most CPU efficient way to do it. + python is ideal for Netdata plugins. It is a simple, yet powerful way to collect data, it has a very small memory footprint, although it is not the most CPU efficient way to do it. 2. **node.js**, use `node.d.plugin`, there are a few examples in the [node.d directory](../node.d.plugin/) @@ -393,7 +393,7 @@ or do not output the line at all. 4. **C** - Of course, C is the most efficient way of collecting data. This is why netdata itself is written in C. + Of course, C is the most efficient way of collecting data. This is why Netdata itself is written in C. ## Writing Plugins Properly @@ -436,7 +436,7 @@ There are a few rules for writing plugins properly: /* * find the time of the next loop * this makes sure we are always aligned - * with the netdata daemon + * with the Netdata daemon */ next_run = now - (now % update_every) + update_every; @@ -461,7 +461,7 @@ There are a few rules for writing plugins properly: /* do your magic here to collect values */ collectValues(); - /* send the collected data to netdata */ + /* send the collected data to Netdata */ printValues(dt_since_last_run); /* print BEGIN, SET, END statements */ } ``` |