-------------------------------------------------------------------------------
NETDATA CUSTOM PLUGINS

custom chart plugins can be any program that can print a few values on its
standard output.

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 script can produce any number of charts with any number of dimensions
each. charts can also be added any time (not just the beginning).

The script 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 script is controlled via the configuration file.

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.


-------------------------------------------------------------------------------
CREATE NEW CHART

 > CHART type.id name title units family[=id] category[=type] charttype[=line]
                                   priority[=1000] update_every[=user default]

 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

 - family
   is used to group charts together.
   (for example all eth0 charts should say: eth0)

 - category
   is not used currently.
   it will be used to set 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

 - charttype
   line, area or stacked

 - 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

 - update_every
   overwrite the update frequency set by the server


-------------------------------------------------------------------------------
ADD DIMENSIONS

 > DIMENSION id name[=id] algorithm[=absolute] multiplier[=1] divisor[=1]
                                                              hidden[=not set]

 where:

 - id
   the id of this dimension (it is a text value, not numeric)
   this will be needed to add values to the dimension

 - name
   the name of the dimension as it will appear at the legend of the chart

 - algorithms
   one of:

   * absolute
     the value is to drawn as-is

   * incremental
     the value increases over time.
     the difference from the last value is presented in the chart.
     the server stretches the difference to produce 1 second increments.
     it does this at the microsecond level.

   * 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 differential total of
     each dimension.

 - multiplier
   a value to multiply the collected value.

 - divisor
   a value to divide the collected value.

 - hidden
   giving the keyword 'hidden' will make this dimension hidden.
   it will take part in the calculation 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

 - type.id
   is the unique identification of the chart (created with CHART)

 > SET id = value

  - id
    is the unique identification of the dimension (of the chart just began)

  - value
    is the collected value

  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.

 > END

 END does not take any parameters.
 it commits the collected values to the chart.
 

 
-------------------------------------------------------------------------------
A NOTE ABOUT 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

 However, to lower its memory requirements, it stores all values in the
 signed 32bit range, divided by 10, that is:

                  -214.748.364   to   +214.748.364

 This division by 10, is used to give a decimal point in the charts.
 In memory, every number is 4 bytes (32bits).

 algorithm, multiplier and divisor help maintain all the detail required.

 The algorithm is applied in the wider 64bit numbers. Once the calculation
 is complete the value is multiplied by the multiplier, by 10, and then
 divided by the divider (all of these at the 64bit level).
 The 64bit result is then stored in a 32 bit signed int.

 So, at the chart level:

  - the finest number is 0.1
  - the smallest -214.748.364,8
  - the highest   214.748.364,7

 You should choose a multiplier and divisor to stay within these limits.

 Example:

 eth0 bytes-in is a 64bit number that is incremented every time.
 let say it is              1.000.000.000.000.000.000
 and one second later it is 1.000.000.000.999.000.000

 the dimension is 'incremental' with multiplier 8 (bytes to bits)
 and divider 1024 (bits to kilobits).

 netdata will store this value:

 value = (1.000.000.000.000.000.000 - 1.000.000.000.999.000.000)
                 * 10
                  * 8
               / 1024
         = 78.046.875

 or 7.804.687,5 kilobits/second (a little less than 8 gigabits/second)