more documentation about charts.d
Costa Tsaousis (ktsaou) committed
May 2, 2014 at 11:23 UTC
a418c8f833e7d20540026a111de7d35ec4e7eff6
2 files changed
+204
-81
charts.d/README
new
+195
@@ -0,0 +1,195 @@
1
+
2
+-------------------------------------------------------------------------------
3
+NETDATA CUSTOM PLUGINS
4
+
5
+custom chart plugins can be any program that can print a few values on its
6
+standard output.
7
+
8
+There are 5 lines netdata parses. lines starting with:
9
+
10
+CHART - create a new chart
11
+DIMENSION - add a dimension to the chart just created
12
+
13
+BEGIN - initialize data collection for a chart
14
+SET - set the value of a dimension for the initialized chart
15
+END - complete data collection for the initialized chart
16
+
17
+a single script can produce any number of charts with any number of dimensions
18
+each. charts can also be added any time (not just the beginning).
19
+
20
+The script should accept just one parameter: the number of seconds it is
21
+expected to update the values for its charts. The value passed by netdata
22
+to the script is controlled via the configuration file.
23
+
24
+The script can overwrite the update frequency. For example, the server may
25
+request per second updates, but the script may overwrite this to one update
26
+every 5 seconds.
27
+
28
+
29
+-------------------------------------------------------------------------------
30
+CREATE NEW CHART
31
+
32
+ > CHART type.id name title units family[=id] category[=type] charttype[=line]
33
+ priority[=1000] update_every[=user default]
34
+
35
+ where:
36
+ - type.id
37
+ uniquely identifies the chart
38
+ this is what will be needed to add values to the chart
39
+
40
+ - name
41
+ is the name that will be presented to the used for this chart
42
+
43
+ - title
44
+ the text above the chart
45
+
46
+ - units
47
+ the label of the vertical axis of the chart
48
+
49
+ - family
50
+ is used to group charts together.
51
+ (for example all eth0 charts should say: eth0)
52
+
53
+ - category
54
+ is not used currently.
55
+ it will be used to set the section under which the chart will appear
56
+ (for example mem.ram should appear in the 'system' section)
57
+ the special word 'none' means: do not show this chart on the home page
58
+
59
+ - charttype
60
+ line, area or stacked
61
+
62
+ - priority
63
+ is the relative priority of the charts as rendered on the web page
64
+ lower numbers make the charts appear before the ones with higher numbers
65
+
66
+ - update_every
67
+ overwrite the update frequency set by the server
68
+
69
+
70
+-------------------------------------------------------------------------------
71
+ADD DIMENSIONS
72
+
73
+ > DIMENSION id name[=id] algorithm[=absolute] multiplier[=1] divisor[=1]
74
+ hidden[=not set]
75
+
76
+ where:
77
+
78
+ - id
79
+ the id of this dimension (it is a text value, not numeric)
80
+ this will be needed to add values to the dimension
81
+
82
+ - name
83
+ the name of the dimension as it will appear at the legend of the chart
84
+
85
+ - algorithms
86
+ one of:
87
+
88
+ * absolute
89
+ the value is to drawn as-is
90
+
91
+ * incremental
92
+ the value increases over time.
93
+ the difference from the last value is presented in the chart.
94
+ the server stretches the difference to produce 1 second increments.
95
+ it does this at the microsecond level.
96
+
97
+ * percentage-of-absolute-row
98
+ the % of this value compared to the total of all dimensions.
99
+
100
+ * percentage-of-incremental-row
101
+ the % of this value compared to the differential total of
102
+ each dimension.
103
+
104
+ - multiplier
105
+ a value to multiply the collected value.
106
+
107
+ - divisor
108
+ a value to divide the collected value.
109
+
110
+ - hidden
111
+ giving the keyword 'hidden' will make this dimension hidden.
112
+ it will take part in the calculation but will not be presented in the chart
113
+
114
+
115
+-------------------------------------------------------------------------------
116
+DATA COLLECTION
117
+
118
+ data collection is defined as a series of BEGIN -> SET -> END lines.
119
+
120
+ > BEGIN type.id
121
+
122
+ - type.id
123
+ is the unique identification of the chart (created with CHART)
124
+
125
+ > SET id = value
126
+
127
+ - id
128
+ is the unique identification of the dimension (of the chart just began)
129
+
130
+ - value
131
+ is the collected value
132
+
133
+ more SET lines may appear to update all the dimensions of the chart.
134
+ all of them in one BEGIN -> END block.
135
+ All SET lines within a single BEGIN -> END block have to refer to the
136
+ same chart. If more charts need to be updated, each chart should have
137
+ its own BEGIN -> SET -> END block.
138
+
139
+ > END
140
+
141
+ END does not take any parameters.
142
+ it commits the collected values to the chart.
143
+
144
+
145
+
146
+-------------------------------------------------------------------------------
147
+A NOTE ABOUT VALUES
148
+
149
+ NetData will collect any signed value in the 64bit range:
150
+
151
+ -9.223.372.036.854.775.808 to +9.223.372.036.854.775.807
152
+
153
+ However, to lower its memory requirements, it stores all values in the
154
+ signed 32bit range, divided by 10, that is:
155
+
156
+ -214.748.364 to +214.748.364
157
+
158
+ This division by 10, is used to give a decimal point in the charts.
159
+ In memory, every number is 4 bytes (32bits).
160
+
161
+ algorithm, multiplier and divisor help maintain all the detail required.
162
+
163
+ The algorithm is applied in the wider 64bit numbers. Once the calculation
164
+ is complete the value is multiplied by the multiplier, by 10, and then
165
+ divided by the divider (all of these at the 64bit level).
166
+ The 64bit result is then stored in a 32 bit signed int.
167
+
168
+ So, at the chart level:
169
+
170
+ - the finest number is 0.1
171
+ - the smallest -214.748.364,8
172
+ - the highest 214.748.364,7
173
+
174
+ You should choose a multiplier and divisor to stay within these limits.
175
+
176
+ Example:
177
+
178
+ eth0 bytes-in is a 64bit number that is incremented every time.
179
+ let say it is 1.000.000.000.000.000.000
180
+ and one second later it is 1.000.000.000.999.000.000
181
+
182
+ the dimension is 'incremental' with multiplier 8 (bytes to bits)
183
+ and divider 1024 (bits to kilobits).
184
+
185
+ netdata will store this value:
186
+
187
+ value = (1.000.000.000.000.000.000 - 1.000.000.000.999.000.000)
188
+ * 10
189
+ * 8
190
+ / 1024
191
+ = 78.046.875
192
+
193
+ or 7.804.687,5 kilobits/second (a little less than 8 gigabits/second)
194
+
195
+
charts.d/skeleton-chart.sh
+9
-81
@@ -1,5 +1,9 @@
1
#!/bin/sh
2
3
+# report our PID back to netdata
4
+# this is required for netdata to kill this process when it exits
5
+echo "MYPID $$"
6
+
7
# default sleep function
8
loopsleepms() {
9
sleep $1
@@ -13,84 +17,9 @@ update_every=$1
17
update_every=$(( update_every + 1 - 1)) # makes sure it is a number
18
test $update_every -eq 0 && update_every=1 # if it is zero, make it 1
19
16
-# report the PID back to netdata
17
-# this is required for netdata to kill this process when it exits
18
-echo "MYPID $$"
19
-
20
-# -----------------------------------------------------------------------------
21
-# DOCUMENTATION
22
-#
23
-# This is a long doc, to describe a simple procedure.
24
-# If you don't want to read it, just skip at the end to see the action...
25
-#
26
-# CREATE NEW CHART:
27
-# > CHART type.id name title units family[=id] category[=type] charttype[=line] priority[=1000] update_every[=user default]
28
-#
29
-# where
30
-# - charttype = line, area or stacked
31
-# - family is used to group charts together (for example all eth0 charts should say: eth0)
32
-# - category = is the home page section: any name or the word 'none' which hides the chart from the home web page
33
-#
34
-# create all the dimensions you need
35
-# > DIMENSION id name algorithm multiplier divisor [hidden]
36
-#
37
-# algorithms:
38
-# absolute
39
-# the value is to drawn as-is
40
-#
41
-# incremental
42
-# the value increases over time
43
-# the difference from the last value is drawn
44
-#
45
-# percentage-of-absolute-row
46
-# the % is drawn of this value compared to the total of all dimensions
47
-#
48
-# percentage-of-incremental-row
49
-# the % is drawn of this value compared to the differential total of
50
-# each dimension
51
-#
52
-# A NOTE ABOUT VALUES
53
-# NetData will collect any signed value in the 64bit range:
54
-#
55
-# -9.223.372.036.854.775.807 to +9.223.372.036.854.775.807
56
-#
57
-# However, to lower its memory requirements, it stores all values in the
58
-# signed 32bit range, divided by 10, that is:
59
-#
60
-# -214.748.364 to 214.748.364
61
-#
62
-# This division by 10, is used to give you a decimal point in the charts.
63
-# In memory, every number is 4 bytes (32bits).
64
-#
65
-# To work with this without loosing detail, you should set the proper
66
-# algorithm of calculation, together with a multiplier and a divider.
67
-#
68
-# The algorithm is applied in the wider 64bit numbers. Once the calculation
69
-# is complete the value is multiplied by the multiplier, by 10, and then
70
-# divided by the divider (all of these at the 64bit level).
71
-# The 64bit result is then stored in a 32 bit signed int.
72
-#
73
-# So, at the chart level:
74
-#
75
-# - the finest number is 0.1
76
-# - the smallest -214.748.364,8
77
-# - the highest 214.748.364,7
78
-#
79
-# You should choose a multiplier and divider to stay within these limits.
80
-#
81
-# Example:
82
-# eth0 bytes-in is a 64bit number that is incremented every time.
83
-# let say it is 1.000.000.000.000.000.000 and one second later it is 1.000.000.000.999.000.000
84
-# the dimension is 'incremental' with multiplier 8 (bytes to bits) and divider 1024 (bits to kilobits).
85
-# netdata will store this value:
86
-#
87
-# value = (1.000.000.000.000.000.000 - 1.000.000.000.999.000.000) * 10 * 8 / 1024 = 78.046.875
88
-# or 7.804.687,5 kilobits/second (a little less than 8 gigabits/second)
89
-#
90
-
91
-
20
+# create the chart with 3 dimensions
21
cat <<EOF
93
-CHART example.random '' "Random Numbers Example Chart" "random numbers" ExampleFamily ExampleCategory stacked 500 $update_every
22
+CHART example.random '' "Random Numbers Example Chart" "random numbers" random random stacked 500 $update_every
23
DIMENSION number1 '' absolute 1 1
24
DIMENSION number2 '' absolute 1 1
25
DIMENSION number3 '' absolute 1 1 hidden
@@ -99,9 +28,11 @@ EOF
28
# You can create more charts if you like.
29
# Just add more chart definitions.
30
31
+# work forever
32
while [ 1 ]
33
do
104
- # do all the work to calculate the numbers
34
+ # do all the work to collect / calculate the values
35
+ # for each dimension
36
37
value1=$RANDOM
38
value2=$RANDOM
@@ -109,8 +40,6 @@ do
40
41
42
# write the result of the work.
112
- # it is important to keep this short.
113
- # between BEGIN and END statements the clients are blocked access to the chart.
43
cat <<VALUESEOF
44
BEGIN example.random
45
SET number1 = $value1
@@ -124,4 +53,3 @@ VALUESEOF
53
# wait the time you are required to
54
loopsleepms $update_every
55
done
127
-