diff options
| author | Joel Hans <joel@netdata.cloud> | 2019-12-03 10:51:26 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2019-12-03 10:51:26 -0700 |
| commit | a2b0c9c702264de9d7039c2edc809bf37111096e (patch) | |
| tree | 17901653b0c04d6eee630889cef375809190c558 /daemon | |
| parent | e5478fac6c84081686fcfae1d9766a964ea5068f (diff) | |
Documentation on per-chart configuration options (#7345)
* Initial re-setup
* Working on dimension settings
* Finished with dimension settings
* Grammar fixes and better incremental description
* Final few fixes
* Fix for Markos
Diffstat (limited to 'daemon')
| -rw-r--r-- | daemon/config/README.md | 78 |
1 files changed, 73 insertions, 5 deletions
diff --git a/daemon/config/README.md b/daemon/config/README.md index 72d961b1eb..409ef6f72f 100644 --- a/daemon/config/README.md +++ b/daemon/config/README.md @@ -120,17 +120,17 @@ To understand what this section is and how it should be configured, please refer Refer to the [streaming and replication](../../streaming) documentation. -### Per plugin configuration +## Per-plugin configuration The configuration options for plugins appear in sections following the pattern `[plugin:NAME]`. -#### Internal plugins +### Internal plugins Most internal plugins will provide additional options. Check [Internal Plugins](../../collectors/) for more information. Please note, that by default Netdata will enable monitoring metrics for disks, memory, and network only when they are not zero. If they are constantly zero they are ignored. Metrics that will start having values, after Netdata is started, will be detected and charts will be automatically added to the dashboard (a refresh of the dashboard is needed for them to appear though). Use `yes` instead of `auto` in plugin configuration sections to enable these charts permanently. You can also set the `enable zero metrics` option to `yes` in the `[global]` section which enables charts with zero metrics for all internal Netdata plugins. -#### External plugins +### External plugins External plugins will have only 2 options at `netdata.conf`: @@ -141,8 +141,76 @@ External plugins will have only 2 options at `netdata.conf`: External plugins that need additional configuration may support a dedicated file in `/etc/netdata`. Check their documentation. -### Per chart configuration +## Per-chart configuration + +In this area of `netdata.conf` you can find configuration options for individual charts. They appear in sections +following the pattern `[NAME]`. + +Using the settings and values under these sections, you can control all aspects of a specific chart. You can change its +title, make it appear higher in Netdata's [menu](../../web/gui/README.md#menus), tweak its dimensions, and much more. + +To find the name of a given chart, and thus the name of its section in `netdata.conf`, look at the top-left corner of a +chart: + + + +Every per-chart configuration section has several common settings, which are listed in the table just below. Beneath +that is information about lines that begin with `dim`, which affect a chart's dimensions. + +| Setting | Function | +| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `history` | Override the `history` setting in the [[global] options](#global-section-options) for this particular chart. Should be less than or equal to the global `history` setting. | +| `enabled` | A boolean (`yes` or `no`) that explicitly enables or disables the chart in question. | +| `cache directory` | The directory where cache files for this plugin, if needed, are stored. | +| `chart type` | Defines what type of chart to display. It can be `line`, `area`, or `stacked`. If empty or missing, `line` will be used. | +| `type` | Uniquely identify which [menu](../../web/gui/README.md#menus) on the Netdata dashboard this chart should appear under. Some examples include `system` (**System**), `disk` (**Disks**), `net` (**Network Interfaces**), and `netdata` (**Netdata Monitoring**). | +| `family` | Change the chart's [family](../../web/README.md#families) from its default. For example, you could force a disk space chart to collect metrics for family `sdb` instead of family `sda`. | +| `units` | Text for the label of the vertical axis of the chart. This means all dimensions should have the same unit of measurement. | +| `context` | Change the default [context](../../web/README.md#contexts) of the chart. Changing this setting will affect what metrics and metrics the chart displays, and which alarms are attached to it. | +| `priority` | Define where the chart should appear on the Netdata dashboard. Lower values equal higher priority, so a priority of `1` will place the chart highest, while a priority of `9999999` would place the chart at the bottom of the Netdata dashboard. | +| `name` | The name of the chart that appears in the top-left corner, after the chart's title. You can also use this name when writing [health entities](../../health/README.md#). | +| `title` | The text that appears above the chart in the Netdata dashboard. | + +### Dimension settings + +You may notice some settings that begin with `dim` beneath the ones defined in the table above. These settings determine +which dimensions appear on the given chart and how Netdata calculates them. + +Each dimension setting has the following structure: `dim [DIMENSION ID] [OPTION] = [VALUE]`. The available options are `name`, `algorithm`, `multipler`, and `divisor`. + +| Setting | Function | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `name` | The name of the dimension as it will appear in the legend of the chart. If left empty, or is missing, Netdata will use the `[DIMENSION ID]` instead. | +| `algorithm` | Can be `absolute`, `incremental`, `percentage-of-absolute-row`, or `percentage-of-incremental-row`. If this setting is empty, invalid, or missing, Netdata will use `absolute`. See the list beneath this table for descriptions of what each algorithm does. | +| `multiplier` | An integer value by which to multiply the collected value. If empty or missing, Netdata will use `1`. This setting is often used with the value `1024` to convert metabytes to kilobytes, kilobytes to bytes, and so on. | +| `divisor` | An integer value by which to divide the collected value. If empty or missing, Netdata will use `1`. This setting is often used with the value `1024` to convert bytes to kilobytes, kilobytes to megabytes, and so on. | + +Here are the options for the `algorithm` setting: + +- `absolute`: The value is drawn as-is (interpolated to second boundary). +- `incremental`: To be used when the value always increases over time, such as the I/O on a disk. Netdata takes the + difference between the current metric and the past metric to calculate 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. + +For example, the `system.io` chart has the following default settings: + +```conf + # dim in name = in + # dim in algorithm = incremental + # dim in multiplier = 1 + # dim in divisor = 1 + # dim out name = out + # dim out algorithm = incremental + # dim out multiplier = -1 + # dim out divisor = 1 +``` + +These `dim` settings produce two dimensions, `in` and `out`, both of which use the `incremental` algorithm. By +multiplying the value of `out` by -1, Netdata creates the negative values seen in the following area chart: -In this section you will find a separate subsection for each chart shown on the dashboard. You can control all aspects of a specific chart here. You can understand what each option does by reading [how charts are defined](../../collectors/plugins.d/#chart). If you don't know how to find the name of a chart, you can learn about it [here](../../web/README.md#charts-contexts-families). + [](<>) |