plugins.d/README.md

   1 netdata plugins
   2 ===============
   3
   4 Any program that can print a few values to its standard output can become
   5 a netdata plugin.
   6
   7 There are 5 lines netdata parses. lines starting with:
   8
   9 - `CHART` - create a new chart
  10 - `DIMENSION` - add a dimension to the chart just created
  11 - `BEGIN` - initialize data collection for a chart
  12 - `SET` - set the value of a dimension for the initialized chart
  13 - `END` - complete data collection for the initialized chart
  14
  15 a single program can produce any number of charts with any number of dimensions
  16 each.
  17
  18 charts can also be added any time (not just the beginning).
  19
  20 ### command line parameters
  21
  22 The plugin should accept just **one** parameter: **the number of seconds it is
  23 expected to update the values for its charts**. The value passed by netdata
  24 to the plugin is controlled via its configuration file (so there is not need
  25 for the plugin to handle this configuration option).
  26
  27 The script can overwrite the update frequency. For example, the server may
  28 request per second updates, but the script may overwrite this to one update
  29 every 5 seconds.
  30
  31 ### environment variables
  32
  33 There are a few environment variables that are set by `netdata` and are
  34 available for the plugin to use.
  35
  36 variable|description
  37 :------:|:----------
  38 `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.
  39 `NETDATA_PLUGINS_DIR`|The directory where all netdata plugins are stored.
  40 `NETDATA_WEB_DIR`|The directory where the web files of netdata are saved.
  41 `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.
  42 `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.
  43 `NETDATA_HOST_PREFIX`|This is used in environments where system directories like `/sys` and `/proc` have to be accessed at a different path.
  44 `NETDATA_DEBUG_FLAGS`|This is number (probably in hex starting with `0x`), that enables certain netdata debugging features.
  45 `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.
  46
  47
  48 # the output of the plugin
  49
  50 The plugin should output instructions for netdata to its output (`stdout`).
  51
  52 ## CHART
  53
  54 `CHART` defines a new chart.
  55
  56 the template is:
  57
  58 > CHART type.id name title units [family [category [charttype [priority [update_every]]]]]
  59
  60  where:
  61   - `type.id`
  62
  63     uniquely identifies the chart,
  64     this is what will be needed to add values to the chart
  65
  66   - `name`
  67
  68     is the name that will be presented to the used for this chart
  69
  70   - `title`
  71
  72     the text above the chart
  73
  74   - `units`
  75
  76     the label of the vertical axis of the chart,
  77     all dimensions added to a chart should have the same units
  78     of measurement
  79
  80   - `family`
  81
  82     is used to group charts together
  83     (for example all eth0 charts should say: eth0),
  84     if empty or missing, the `id` part of `type.id` will be used
  85
  86   - `category`
  87
  88     the section under which the chart will appear
  89     (for example mem.ram should appear in the 'system' section),
  90     the special word 'none' means: do not show this chart on the home page,
  91     if empty or missing, the `type` part of `type.id` will be used
  92
  93   - `charttype`
  94
  95     one of `line`, `area` or `stacked`,
  96     if empty or missing, the `line` will be used
  97
  98   - `priority`
  99
 100     is the relative priority of the charts as rendered on the web page,
 101     lower numbers make the charts appear before the ones with higher numbers,
 102     if empty or missing, `1000` will be used
 103
 104   - `update_every`
 105
 106     overwrite the update frequency set by the server,
 107     if empty or missing, the user configured value will be used
 108
 109
 110 ## DIMENSION
 111
 112 `DIMENSION` defines a new dimension for the chart
 113
 114 the template is:
 115
 116 > DIMENSION id [name [algorithm [multiplier [divisor [hidden]]]]]
 117
 118  where:
 119
 120   - `id`
 121
 122     the `id` of this dimension (it is a text value, not numeric),
 123     this will be needed later to add values to the dimension
 124
 125   - `name`
 126
 127     the name of the dimension as it will appear at the legend of the chart,
 128     if empty or missing the `id` will be used
 129
 130   - `algorithm`
 131
 132     one of:
 133
 134     * `absolute`
 135
 136       the value is to drawn as-is (interpolated to second boundary),
 137       if `algorithm` is empty, invalid or missing, `absolute` is used
 138
 139     * `incremental`
 140
 141       the value increases over time,
 142       the difference from the last value is presented in the chart,
 143       the server interpolates the value and calculates a per second figure
 144
 145     * `percentage-of-absolute-row`
 146
 147       the % of this value compared to the total of all dimensions
 148
 149     * `percentage-of-incremental-row`
 150
 151       the % of this value compared to the incremental total of
 152       all dimensions
 153
 154   - `multiplier`
 155
 156     an integer value to multiply the collected value,
 157     if empty or missing, `1` is used
 158
 159   - `divisor`
 160
 161     an integer value to divide the collected value,
 162     if empty or missing, `1` is used
 163
 164   - `hidden`
 165
 166     giving the keyword `hidden` will make this dimension hidden,
 167     it will take part in the calculations but will not be presented in the chart
 168
 169
 170 ## data collection
 171
 172 data collection is defined as a series of `BEGIN` -> `SET` -> `END` lines
 173
 174 > BEGIN type.id [microseconds]
 175
 176   - `type.id`
 177
 178     is the unique identification of the chart (as given in `CHART`)
 179
 180   - `microseconds`
 181
 182     is the number of microseconds since the last update of the chart,
 183     it is optional.
 184
 185     Under heavy system load, the system may have some latency transfering
 186     data from the plugins to netdata via the pipe. This number improves
 187     accuracy significantly, since the plugin is able to calculate the
 188     duration between its iterations better than netdata.
 189
 190     The first time the plugin is started, no microseconds should be given
 191     to netdata.
 192
 193 > SET id = value
 194
 195    - `id`
 196
 197      is the unique identification of the dimension (of the chart just began)
 198
 199    - `value`
 200
 201      is the collected value
 202
 203 > END
 204
 205   END does not take any parameters, it commits the collected values to the chart.
 206
 207 More `SET` lines may appear to update all the dimensions of the chart.
 208 All of them in one `BEGIN` -> `END` block.
 209
 210 All `SET` lines within a single `BEGIN` -> `END` block have to refer to the
 211 same chart.
 212
 213 If more charts need to be updated, each chart should have its own
 214 `BEGIN` -> `SET` -> `END` block.
 215
 216 If, for any reason, a plugin has issued a `BEGIN` but wants to cancel it,
 217 it can issue a `FLUSH`. The `FLUSH` command will instruct netdata to ignore
 218 the last `BEGIN` command.
 219
 220 If a plugin does not behave properly (outputs invalid lines, or does not
 221 follow these guidelines), will be disabled by netdata.
 222
 223
 224 ### collected values
 225
 226 netdata will collect any **signed** value in the 64bit range:
 227 `-9.223.372.036.854.775.808` to `+9.223.372.036.854.775.807`
 228
 229 Internally, all calculations are made using 128 bit double precision and are
 230 stored in 30 bits as floating point.
 231
 232 If a value is not collected, leave it empty, like this:
 233
 234 `SET id = `
 235
 236 or do not output the line at all.