------------------------------------------------------------------------------- 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)