README.md · cryptotaxi247/netdata-1

Code Commits Issues Pulls Sessions CI/CD

master

md 360 lines 19.7 KB

Rendered Raw

1	# Netdata badges
2
3	Badges are cool!
4
5	Netdata can generate badges for any chart and any dimension at any time-frame. Badges come in `SVG` and can be added to any web page using an `<IMG>` HTML tag.
6
7	Netdata badges are powerful!
8
9	Given that Netdata collects from 1.000 to 5.000 metrics per server (depending on the number of network interfaces, disks, cpu cores, applications running, users logged in, containers running, etc) and that Netdata already has data reduction/aggregation functions embedded, the badges can be quite powerful.
10
11	For each metric/dimension and for arbitrary time-frames badges can show min, max or average value, but also sum or incremental-sum to have their volume.
12
13	For example, there is [a chart in Netdata that shows the current requests/s of nginx](http://london.my-netdata.io/#nginx_local_nginx). Using this chart alone we can show the following badges (we could add more time-frames, like today, yesterday, etc):
14
15	<a href="https://registry.my-netdata.io/#nginx_local_nginx"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=nginx_local.connections&dimensions=active&value_color=grey:null%7Cblue&label=nginx%20active%20connections%20now&units=null&precision=0"/></a> <a href="https://registry.my-netdata.io/#nginx_local_nginx"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=nginx_local.connections&dimensions=active&after=-3600&value_color=orange&label=last%20hour%20average&units=null&options=unaligned&precision=0"/></a> <a href="https://registry.my-netdata.io/#nginx_local_nginx"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=nginx_local.connections&dimensions=active&group=max&after=-3600&value_color=red&label=last%20hour%20max&units=null&options=unaligned&precision=0"/></a>
16
17	Similarly, there is [a chart that shows outbound bandwidth per class](http://london.my-netdata.io/#tc_eth0), using QoS data. So it shows `kilobits/s` per class. Using this chart we can show:
18
19	<a href="https://registry.my-netdata.io/#tc_eth0"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=tc.world_out&dimensions=web_server&value_color=green&label=web%20server%20sends%20now&units=kbps"/></a> <a href="https://registry.my-netdata.io/#tc_eth0"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=tc.world_out&dimensions=web_server&after=-86400&options=unaligned&group=sum&divide=8388608&value_color=blue&label=web%20server%20sent%20today&units=GB"/></a>
20
21	The right one is a volume calculation. Netdata calculated the total of the last 86.400 seconds (a day) which gives `kilobits`, then divided it by 8 to make it KB, then by 1024 to make it MB and then by 1024 to make it GB. Calculations like this are quite accurate, since for every value collected, every second, Netdata interpolates it to second boundary using microsecond calculations.
22
23	Let's see a few more badge examples (they come from the [Netdata Registry](/src/registry/README.md)):
24
25	- cpu usage of user `root` (you can pick any user; 100% = 1 core). This will be `green <10%`, `yellow <20%`, `orange <50%`, `blue <100%` (1 core), `red` otherwise (you define thresholds and colors on the URL).
26
27	<a href="https://registry.my-netdata.io/#apps_cpu"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20cpu%20now&units=%25"></img></a> <a href="https://registry.my-netdata.io/#apps_cpu"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&after=-3600&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20average%20cpu%20last%20hour&units=%25"></img></a>
28
29	- mysql queries per second
30
31	<a href="https://registry.my-netdata.io/#mysql_local"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=mysql_local.queries&dimensions=questions&label=mysql%20queries%20now&value_color=red&units=%5Cs"></img></a> <a href="https://registry.my-netdata.io/#mysql_local"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=mysql_local.queries&dimensions=questions&after=-3600&options=unaligned&group=sum&label=mysql%20queries%20this%20hour&value_color=green&units=null"></img></a> <a href="https://registry.my-netdata.io/#mysql_local"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=mysql_local.queries&dimensions=questions&after=-86400&options=unaligned&group=sum&label=mysql%20queries%20today&value_color=blue&units=null"></img></a>
32
33	niche ones: mysql SELECT statements with JOIN, which did full table scans:
34
35	<a href="https://registry.my-netdata.io/#mysql_local_issues"><img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=mysql_local.join_issues&dimensions=scan&after=-3600&label=full%20table%20scans%20the%20last%20hour&value_color=orange&group=sum&units=null"></img></a>
36
37	---
38
39	> So, every single line on the charts of a [Netdata dashboard](http://london.my-netdata.io/), can become a badge and this badge can calculate average, min, max, or volume for any time-frame! And you can also vary the badge color using conditions on the calculated value.
40
41	---
42
43	## How to create badges
44
45	The basic URL is `http://your.netdata:19999/api/v1/badge.svg?option1&option2&option3&...`.
46
47	Here is what you can put for `options` (these are standard Netdata API options):
48
49	- `chart=CHART.NAME`
50
51	The chart to get the values from.
52
53	This is the only parameter required and with just this parameter, Netdata will return the sum of the latest values of all chart dimensions.
54
55	Example:
56
57	```html
58	<a href="#">
59	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu"></img>
60	</a>
61	```
62
63	Which produces this:
64
65	<a href="#">
66	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu"></img>
67	</a>
68
69	- `alarm=NAME`
70
71	Render the current value and status of an alert linked to the chart. This option can be ignored if the badge to be generated is not related to an alert.
72
73	The current value of the alert will be rendered. The color of the badge will indicate the status of the alert.
74
75	For alert badges, both `chart` and `alarm` parameters are required.
76
77	- `dimensions=DIMENSION1\|DIMENSION2\|...`
78
79	The dimensions of the chart to use. If you don't set any dimension, all will be used. When multiple dimensions are used, Netdata will sum their values. You can append `options=absolute` if you want this sum to convert all values to positive before adding them.
80
81	Pipes in HTML have to escaped with `%7C`.
82
83	Example:
84
85	```html
86	<a href="#">
87	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&dimensions=system%7Cnice"></img>
88	</a>
89	```
90
91	Which produces this:
92
93	<a href="#">
94	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&dimensions=system%7Cnice"></img>
95	</a>
96
97	- `before=SECONDS` and `after=SECONDS`
98
99	The timeframe. These can be absolute unix timestamps, or relative to now, number of seconds. By default `before=0` and `after=-1` (1 second in the past).
100
101	To get the last minute set `after=-60`. This will give the average of the last complete minute (XX:XX:00 - XX:XX:59).
102
103	To get the max of the last hour set `after=-3600&group=max`. This will give the maximum value of the last complete hour (XX:00:00 - XX:59:59)
104
105	Example:
106
107	```html
108	<a href="#">
109	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60"></img>
110	</a>
111	```
112
113	Which produces the average of last complete minute (XX:XX:00 - XX:XX:59):
114
115	<a href="#">
116	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60"></img>
117	</a>
118
119	While this is the previous minute (one minute before the last one, again aligned XX:XX:00 - XX:XX:59):
120
121	```html
122	<a href="#">
123	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&before=-60&after=-60"></img>
124	</a>
125	```
126
127	It produces this:
128
129	<a href="#">
130	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&before=-60&after=-60"></img>
131	</a>
132
133	- `group=min` or `group=max` or `group=average` (the default) or `group=sum` or `group=incremental-sum`
134
135	If Netdata will have to reduce (aggregate) the data to calculate the value, which aggregation method to use.
136
137	- `max` will find the max value for the timeframe. This works on both positive and negative dimensions. It will find the most extreme value.
138
139	- `min` will find the min value for the timeframe. This works on both positive and negative dimensions. It will find the number closest to zero.
140
141	- `average` will calculate the average value for the timeframe.
142
143	- `sum` will sum all the values for the timeframe. This is nice for finding the volume of dimensions for a timeframe. So if you have a dimension that reports `X per second`, you can find the volume of the dimension in a timeframe, by adding its values in that timeframe.
144
145	- `incremental-sum` will sum the difference of each value to its next. Let's assume you have a dimension that does not measure the rate of something, but the absolute value of it. So it has values like this "1, 5, 3, 7, 4". `incremental-sum` will calculate the difference of adjacent values. In this example, they will be `(5 - 1) + (3 - 5) + (7 - 3) + (4 - 7) = 3` (which is equal to the last value minus the first = 4 - 1).
146
147	- `options=opt1\|opt2\|opt3\|...`
148
149	These fine tune various options of the API. Here is what you can use for badges (the API has more option, but only these are useful for badges):
150
151	- `percentage`, instead of returning a value, calculate the percentage of the sum of the values of the selected dimensions (selected sum / total sum * 100). This also sets the units to `%`.
152
153	- `absolute` or `abs`, turn all values positive and then sum them.
154
155	- `display_absolute` or `display-absolute`, to use the signed value during color calculation, but display the absolute value on the badge.
156
157	- `min2max`, when multiple dimensions are given, do not sum them, but take their `max - min`.
158
159	- `unaligned`, when data are reduced / aggregated (e.g. the request is about the average of the last minute, or hour), Netdata by default aligns them so that the charts will have a constant shape (so average per minute returns always XX:XX:00 - XX:XX:59). Setting the `unaligned` option, Netdata will aggregate data without any alignment, so if the request is for 60 seconds, it will aggregate the latest 60 seconds of collected data.
160
161	These are options dedicated to badges:
162
163	- `label=TEXT`
164
165	The label of the badge.
166
167	- `units=TEXT`
168
169	The units of the badge. If you want to put a `/`, please put a `\`. This is because Netdata allows badges parameters to be given as path in URL, instead of query string. You can also use `null` or `empty` to show it without any units.
170
171	The units `seconds`, `minutes` and `hours` trigger special formatting. The value has to be in this unit, and Netdata will automatically change it to show a more pretty duration.
172
173	- `multiply=NUMBER`
174
175	Multiply the value with this number. The default is `1`.
176
177	- `divide=NUMBER`
178
179	Divide the value with this number. The default is `1`.
180
181	- Color customization parameters
182
183	The following parameters specify colors of each individual part of the badge. Each parameter is documented in detail
184	below.
185
186	\| Area of badge \| Background color parameter \| Text color parameter \|
187	\| ---: \| :------------------------: \| :------------------: \|
188	\| Label (left) part \| `label_color` \| `text_color_lbl` \|
189	\| Value (right) part \| `value_color` \| `text_color_val` \|
190
191	- `label_color=COLOR`
192
193	The color of the label (the left part). You can use any HTML color in `RGB` or `RRGGBB` hex notation (without
194	the `#` character at the beginning). Additionally, you can use one of the following predefined colors (and you
195	can use them by their name):
196
197	- `green`
198	- `brightgreen`
199	- `yellow`
200	- `yellowgreen`
201	- `orange`
202	- `red`
203	- `blue`
204	- `grey`
205	- `gray`
206	- `lightgrey`
207	- `lightgray`
208
209	These colors are taken from <https://github.com/badges/shields>, which makes them compatible with standard
210	badges.
211
212	- `value_color=COLOR:null\|COLOR<VALUE\|COLOR>VALUE\|COLOR>=VALUE\|COLOR<=VALUE\|...`
213
214	You can add a pipe delimited list of conditions to pick the value color. The first matching (left to right) will
215	be used.
216
217	Example: `value_color=grey:null\|green<10\|yellow<100\|orange<1000\|blue<10000\|red`
218
219	The above will set `grey` if no value exists (not collected within the `gap when lost iterations above` in
220	`netdata.conf` for the chart), `green` if the value is less than 10, `yellow` if the value is less than 100, and
221	so on. Netdata will use `red` if no other conditions match. Only integers are supported as values.
222
223	The supported operators are `<`, `>`, `<=`, `>=`, `=` (or `:`), and `!=` (or `<>`).
224
225	You can also use the same syntax as the `label_color` parameter to define each of these colors. You can
226	reference a predefined color by name or `RGB`/`RRGGBB` hex notation.
227
228	- `text_color_lbl=RGB` or `text_color_lbl=RRGGBB` or `text_color_lbl=color_by_name`
229
230	This value specifies the font color for the font of left/label side of the badge. The syntax is the same as the
231	`label_color` parameter. If not given, or given with an empty value, Netdata will use the default color.
232
233	- `text_color_val=RGB` or `text_color_val=RRGGBB` or `text_color_lbl=color_by_name`
234
235	This value specifies the font color for the font of right/value side of the badge. The syntax is the same as the
236	`label_color` parameter. If not given, or given with an empty value, Netdata will use the default color.
237
238	- `precision=NUMBER`
239
240	The number of decimal digits of the value. By default Netdata will add:
241
242	- no decimal digits for values > 1000
243	- 1 decimal digit for values > 100
244	- 2 decimal digits for values > 1
245	- 3 decimal digits for values > 0.1
246	- 4 decimal digits for values \<= 0.1
247
248	Using the `precision=NUMBER` you can set your preference per badge.
249
250	- `scale=XXX`
251
252	This option scales the svg image. It accepts values above or equal to 100 (100% is the default scale). For example, lets get a few different sizes:
253
254	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60&scale=100"></img> original<br/>
255	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60&scale=125"></img> `scale=125`<br/>
256	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60&scale=150"></img> `scale=150`<br/>
257	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60&scale=175"></img> `scale=175`<br/>
258	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60&scale=200"></img> `scale=200`
259
260	- `fixed_width_lbl=NUMBER` and `fixed_width_val=NUMBER`
261
262	This parameter overrides auto-sizing of badges and displays them at fixed widths. `fixed_width_lbl` determines the size of the label's left side (label/name). `fixed_width_val` determines the size of the label's right side (value). You must set both parameters together, or they will be ignored.
263
264	You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you're requesting. In case the text cannot fit the space given it will be clipped.
265
266	The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`.
267
268	- `refresh=auto` or `refresh=SECONDS`
269
270	This option enables auto-refreshing of images. Netdata will send the HTTP header `Refresh: SECONDS` to the web browser, thus requesting automatic refresh of the images at regular intervals.
271
272	`auto` will calculate the proper `SECONDS` to avoid unnecessary refreshes. If `SECONDS` is zero, this feature is disabled (it is also disabled by default).
273
274	Auto-refreshing like this, works only if you access the badge directly. So, you may have to put it an `embed` or `iframe` for it to be auto-refreshed. Use something like this:
275
276	```html
277	<embed src="BADGE_URL" type="image/svg+xml" height="20" />
278	```
279
280	Another way is to use javascript to auto-refresh them. You can auto-refresh all the Netdata badges on a page using javascript. You have to add a class to all the Netdata badges, like this `<img class="netdata-badge" src="..."/>`. Then add this javascript code to your page (it requires jquery):
281
282	```html
283	<script>
284	var NETDATA_BADGES_AUTOREFRESH_SECONDS = 5;
285	function refreshNetdataBadges() {
286	var now = new Date().getTime().toString();
287	$('.netdata-badge').each(function() {
288	this.src = this.src.replace(/\&_=\d*/, '') + '&_=' + now;
289	});
290	setTimeout(refreshNetdataBadges, NETDATA_BADGES_AUTOREFRESH_SECONDS * 1000);
291	}
292	setTimeout(refreshNetdataBadges, NETDATA_BADGES_AUTOREFRESH_SECONDS * 1000);
293	</script>
294	```
295
296	A more advanced badges refresh method is to include `http://your.netdata.ip:19999/refresh-badges.js` in your page.
297
298	---
299
300	## Escaping URLs
301
302	Keep in mind that if you add badge URLs to your HTML pages you have to escape the special characters:
303
304	\|character\|name\|escape sequence\|
305	\|:-------:\|:--:\|:-------------:\|
306	\|``\|space (in labels and units)\|`%20`\|
307	\|`#`\|hash (for colors)\|`%23`\|
308	\|`%`\|percent (in units)\|`%25`\|
309	\|`<`\|less than\|`%3C`\|
310	\|`>`\|greater than\|`%3E`\|
311	\|`\`\|backslash (when you need a `/`)\|`%5C`\|
312	\|`\\|`\|pipe (delimiting parameters)\|`%7C`\|
313
314	## FAQ
315
316	#### Is it fast?
317
318	On modern hardware, Netdata can generate about 2.000 badges per second per core, before noticing any delays. It generates a badge in about half a millisecond!
319
320	Of course these timing are for badges that use recent data. If you need badges that do calculations over long durations (a day, or more), timing will differ. Netdata logs its timings at its `access.log`, so take a look there before adding a heavy badge on a busy web site. Of course, you can cache such badges or have a cron job get them from Netdata and save them at your web server at regular intervals.
321
322	#### Embedding badges in GitHub
323
324	You have 2 options:
325	- SVG images with markdown
326	- SVG images with HTML (directly in .md files)
327
328	For example, this is the cpu badge shown above:
329
330	- Markdown example:
331
332	```md
333	[![A nice name](https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20cpu%20now&units=%25)](https://registry.my-netdata.io/#apps_cpu)
334	```
335
336	- HTML example:
337
338	```html
339	<a href="https://registry.my-netdata.io/#apps_cpu">
340	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20cpu%20now&units=%25"></img>
341	</a>
342	```
343
344	Both produce this:
345
346	<a href="https://registry.my-netdata.io/#apps_cpu">
347	<img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20cpu%20now&units=%25"></img>
348	</a>
349
350	#### Auto-refreshing badges in GitHub
351
352	Unfortunately it cannot be done. GitHub fetches all the images using a proxy and rewrites all the URLs to be served by the proxy.
353
354	You can refresh them from your browser console though. Press F12 to open the web browser console (switch to the console too), paste the following and press enter. They will refresh:
355
356	```js
357	var len = document.images.length; while(len--) { document.images[len].src = document.images[len].src.replace(/\?cacheBuster=\d*/, "") + "?cacheBuster=" + new Date().getTime().toString(); };
358	```
359
360