Statsd dashboard (#10640)
* revamp statsd docs Signed-off-by: odyslam <odyslam@gmail.com> * Add StatD definition to dashboard_info.js
Odysseas Lamtzidis committed
Feb 22, 2021 at 17:30 UTC
e1f5a8db556265c9cebfb844ecd3887e559e3c0a
2 files changed
+163
-84
collectors/statsd.plugin/README.md
+158
-83
@@ -6,17 +6,19 @@ custom_edit_url: https://github.com/netdata/netdata/edit/master/collectors/stats
6
7
# statsd.plugin
8
9
-statsd is a system to collect data from any application. Applications are sending metrics to it, usually via non-blocking UDP communication, and statsd servers collect these metrics, perform a few simple calculations on them and push them to backend time-series databases.
9
+StatsD is a system to collect data from any application. Applications send metrics to it, usually via non-blocking UDP communication, and StatsD servers collect these metrics, perform a few simple calculations on them and push them to backend time-series databases.
10
+
11
+If you want to learn more about the StatsD protocol, we have written a [blog post](https://www.netdata.cloud/blog/introduction-to-statsd/) about it!
12
13
There is a [plethora of client libraries](https://github.com/etsy/statsd/wiki#client-implementations) for embedding statsd metrics to any application framework. This makes statsd quite popular for custom application metrics.
14
13
-Netdata is a fully featured statsd server. It can collect statsd formatted metrics, visualize them on its dashboards, stream them to other Netdata servers or archive them to backend time-series databases.
15
+Netdata is a fully featured statsd server. It can collect statsd formatted metrics, visualize them on its dashboards and store them in it's database for long-term retention.
16
15
-Netdata statsd is inside Netdata (an internal plugin, running inside the Netdata daemon), it is configured via `netdata.conf` and by-default listens on standard statsd ports (tcp and udp 8125 - yes, Netdata statsd server supports both tcp and udp at the same time).
17
+Netdata statsd is inside Netdata (an internal plugin, running inside the Netdata daemon), it is configured via `netdata.conf` and by-default listens on standard statsd port 8125. Netdata supports both tcp and udp packets at the same time.
18
17
-Since statsd is embedded in Netdata, it means you now have a statsd server embedded on all your servers. So, the application can send its metrics to `localhost:8125`. This provides a distributed statsd implementation.
19
+Since statsd is embedded in Netdata, it means you now have a statsd server embedded on all your servers.
20
19
-Netdata statsd is fast. It can collect more than **1.200.000 metrics per second** on modern hardware, more than **200Mbps of sustained statsd traffic**, using 1 CPU core (yes, it is single threaded - actually double-threaded, one thread collects metrics, another one updates the charts from the collected data).
21
+Netdata statsd is fast. It can collect more than **1.200.000 metrics per second** on modern hardware, more than **200Mbps of sustained statsd traffic**, using 1 CPU core. The implementation uses two threads: one thread collects metrics, another one updates the charts from the collected data.
22
23
## Metrics supported by Netdata
24
@@ -28,7 +30,7 @@ Netdata fully supports the statsd protocol. All statsd client libraries can be u
30
31
The application may increment or decrement a previous value, by setting the first character of the value to `+` or `-` (so, the only way to set a gauge to an absolute negative value, is to first set it to zero).
32
31
- Sampling rate is supported (check below).
33
+ [Sampling rate](#sampling-rates) is supported.
34
35
When a gauge is not collected and the setting is not to show gaps on the charts (the default), the last value will be shown, until a data collection event changes it.
36
@@ -38,21 +40,25 @@ Netdata fully supports the statsd protocol. All statsd client libraries can be u
40
41
`:value` can be omitted and statsd will assume it is `1`. `|c`, `|C` and `|m` can be omitted an statsd will assume it is `|m`. So, the application may send just `name` and statsd will parse it as `name:1|m`.
42
41
- For counters use `|c` (etsy/statsd compatible) or `|C` (brubeck compatible), for meters use `|m`.
42
-
43
- Sampling rate is supported (check below).
43
+ - Counters use `|c` (etsy/statsd compatible) or `|C` (brubeck compatible)
44
+ - Meters use `|m`
45
45
- When a counter or meter is not collected and the setting is not to show gaps on the charts (the default), zero will be shown, until a data collection event changes it.
46
+ [Sampling rate](#sampling-rates) is supported.
47
48
+ When a counter or meter is not collected, Netdata **defaults** to showing a zero value, until a data collection event changes the value.
49
+
50
- **Timers** and **Histograms**
51
52
The application sends `name:value|ms` or `name:value|h`, where `value` is any **decimal/fractional** number, statsd reports **min**, **max**, **average**, **sum**, **95th percentile**, **median** and **standard deviation** and the total number of times it was updated (events).
53
51
- For timers use `|ms`, or histograms use `|h`. The only difference between the two, is the `units` of the charts (timers report milliseconds).
54
+ - Timers use `|ms`
55
+ - Histograms use `|h`
56
+
57
+ The only difference between the two, is the `units` of the charts, as timers report *miliseconds*.
58
53
- Sampling rate is supported (check below).
59
+ [Sampling rate](#sampling-rates) is supported.
60
55
- When a timer or histogram is not collected and the setting is not to show gaps on the charts (the default), zero will be shown, until a data collection event changes it.
61
+ When a counter or meter is not collected, Netdata **defaults** to showing a zero value, until a data collection event changes the value.
62
63
- **Sets**
64
@@ -60,15 +66,15 @@ Netdata fully supports the statsd protocol. All statsd client libraries can be u
66
67
Sampling rate is **not** supported for Sets. `value` is always considered text.
68
63
- When a set is not collected and the setting is not to show gaps on the charts (the default), zero will be shown, until a data collection event changes it.
69
+ When a counter or meter is not collected, Netdata **defaults** to showing a zero value, until a data collection event changes the value.
70
71
#### Sampling Rates
72
67
-The application may append `|@sampling_rate`, where `sampling_rate` is a number from `0.0` to `1.0`, to have statsd extrapolate the value, to predict to total for the whole period. So, if the application reports to statsd a value for 1/10th of the time, it can append `|@0.1` to the metrics it sends to statsd.
73
+The application may append `|@sampling_rate`, where `sampling_rate` is a number from `0.0` to `1.0` in order for StatD to extrapolate the value and predict the total for the entire period. If the application reports to StatsD a value for 1/10th of the time, it can append `|@0.1` to the metrics it sends to statsd.
74
75
#### Overlapping metrics
76
71
-Netdata's statsd server maintains different indexes for each of the types supported. This means the same metric `name` may exist under different types concurrently.
77
+Netdata's StatsD server maintains different indexes for each of the types supported. This means the same metric `name` may exist under different types concurrently.
78
79
#### Multiple metrics per packet
80
@@ -76,15 +82,21 @@ Netdata accepts multiple metrics per packet if each is terminated with `\n`.
82
83
#### TCP packets
84
79
-Netdata listens for both TCP and UDP packets. For TCP though, is it important to always append `\n` on each metric. Netdata uses this to detect if a metric is split into multiple TCP packets. On disconnect, even the remaining (non terminated with `\n`) buffer, is processed.
85
+Netdata listens for both TCP and UDP packets. For TCP, is it important to always append `\n` on each metric, as Netdata will use the newline character to detect if a metric is split into multiple TCP packets.
86
+
87
+On disconnect, Netdata will process the entire buffer, even if it is not terminated with a `\n`.
88
89
#### UDP packets
90
83
-When sending multiple packets over UDP, it is important not to exceed the network MTU (usually 1500 bytes minus a few bytes for the headers). Netdata will accept UDP packets up to 9000 bytes, but the underlying network will not exceed MTU.
91
+When sending multiple packets over UDP, it is important not to exceed the network MTU, usually about 1500 packets.
92
85
-## configuration
93
+Netdata will accept UDP packets up to 9000 bytes, but the underlying network will not exceed MTU.
94
87
-This is the statsd configuration at `/etc/netdata/netdata.conf`:
95
+> You can read more about the network maxium transmission unit(MTU) in this cloudflare [article](https://www.cloudflare.com/en-gb/learning/network-layer/what-is-mtu/).
96
+
97
+## Configuration
98
+
99
+You can find the configuration at `/etc/netdata/netdata.conf`:
100
101
```
102
[statsd]
@@ -110,47 +122,51 @@ This is the statsd configuration at `/etc/netdata/netdata.conf`:
122
# bind to = udp:localhost:8125 tcp:localhost:8125
123
```
124
113
-### statsd main config options
125
+### StatsD main config options
126
127
- `enabled = yes|no`
128
117
- controls if statsd will be enabled for this Netdata. The default is enabled.
129
+ controls if StatsD will be enabled for this Netdata. The default is enabled.
130
131
- `default port = 8125`
132
121
- controls the port statsd will use. This is the default, since the next line, allows defining ports too.
133
+ controls the default port StatsD will use if no port is defined in the following setting.
134
135
- `bind to = udp:localhost tcp:localhost`
136
137
is a space separated list of IPs and ports to listen to. The format is `PROTOCOL:IP:PORT` - if `PORT` is omitted, the `default port` will be used. If `IP` is IPv6, it needs to be enclosed in `[]`. `IP` can also be `*` (to listen on all IPs) or even a hostname.
138
127
-- `update every (flushInterval) = 1` seconds, controls the frequency statsd will push the collected metrics to Netdata charts.
139
+- `update every (flushInterval) = 1` seconds, controls the frequency StatsD will push the collected metrics to Netdata charts.
140
141
- `decimal detail = 1000` controls the number of fractional digits in gauges and histograms. Netdata collects metrics using signed 64 bit integers and their fractional detail is controlled using multipliers and divisors. This setting is used to multiply all collected values to convert them to integers and is also set as the divisors, so that the final data will be a floating point number with this fractional detail (1000 = X.0 - X.999, 10000 = X.0 - X.9999, etc).
142
143
The rest of the settings are discussed below.
144
133
-## statsd charts
145
+## StatsD charts
146
135
-Netdata can visualize statsd collected metrics in 2 ways:
147
+Netdata can visualize StatsD collected metrics in 2 ways:
148
137
-1. Each metric gets its own **private chart**. This is the default and does not require any configuration (although there are a few options to tweak).
149
+1. Each metric gets its own **private chart**. This is the default and does not require any configuration. You can adjust the default parameters.
150
151
2. **Synthetic charts** can be created, combining multiple metrics, independently of their metric types. For this type of charts, special configuration is required, to define the chart title, type, units, its dimensions, etc.
152
141
-### private metric charts
153
+### Private metric charts
154
143
-Private charts are controlled with `create private charts for metrics matching = *`. This setting accepts a space separated list of simple patterns (use `*` as wildcard, prepend a pattern with `!` for a negative match, the order of patterns is important).
155
+Private charts are controlled with `create private charts for metrics matching = *`. This setting accepts a space separated list of [simple patterns](/libnetdata/simple_pattern/README.md). Netdata will create private charts for all metrics **by default**
156
145
-So to render charts for all `myapp.*` metrics, except `myapp.*.badmetric`, use:
157
+For example, to render charts for all `myapp.*` metrics, except `myapp.*.badmetric`, use:
158
159
```
160
create private charts for metrics matching = !myapp.*.badmetric myapp.*
161
```
162
151
-The default is to render private charts for all metrics.
163
+You can specify Netdata StatsD to have a different `memory mode` than the rest of the Netdata Agent. You can read more about `memory mode` in the [documentation](/database/README.md).
164
+
165
+The default behavior is to use the same settings as the rest of the Netdata Agent. If you wish to change them, edit the following settings:
166
+- `private charts memory mode`
167
+- `private charts history`
168
153
-The `memory mode` of the round robin database and the `history` of private metric charts are controlled with `private charts memory mode` and `private charts history`. The defaults for both settings is to use the global Netdata settings. So, you need to edit them only when you want statsd to use different settings compared to the global ones.
169
+### Optimise private metric charts visualization and storage
170
171
If you have thousands of metrics, each with its own private chart, you may notice that your web browser becomes slow when you view the Netdata dashboard (this is a web browser issue we need to address at the Netdata UI). So, Netdata has a protection to stop creating charts when `max private charts allowed = 200` (soft limit) is reached.
172
@@ -160,19 +176,19 @@ Metrics above the hard limit are still collected, but they can only be used in s
176
177
Example private charts (automatically generated without any configuration):
178
163
-#### counters
179
+#### Counters
180
181
- Scope: **count the events of something** (e.g. number of file downloads)
182
- Format: `name:INTEGER|c` or `name:INTEGER|C` or `name|c`
167
-- statsd increments the counter by the `INTEGER` number supplied (positive, or negative).
183
+- StatsD increments the counter by the `INTEGER` number supplied (positive, or negative).
184
185
186
171
-#### gauges
187
+#### Gauges
188
189
- Scope: **report the value of something** (e.g. cache memory used by the application server)
190
- Format: `name:FLOAT|g`
175
-- statsd remembers the last value supplied, and can increment or decrement the latest value if `FLOAT` begins with `+` or `-`.
191
+- StatsD remembers the last value supplied, and can increment or decrement the latest value if `FLOAT` begins with `+` or `-`.
192
193
194
@@ -180,56 +196,57 @@ Example private charts (automatically generated without any configuration):
196
197
- Scope: **statistics on a size of events** (e.g. statistics on the sizes of files downloaded)
198
- Format: `name:FLOAT|h`
183
-- statsd maintains a list of all the values supplied and provides statistics on them.
199
+- StatsD maintains a list of all the values supplied and provides statistics on them.
200
201
202
203
The same chart with `sum` unselected, to show the detail of the dimensions supported:
204
205
190
-#### meters
206
+#### Meters
207
208
This is identical to `counter`.
209
210
- Scope: **count the events of something** (e.g. number of file downloads)
211
- Format: `name:INTEGER|m` or `name|m` or just `name`
196
-- statsd increments the counter by the `INTEGER` number supplied (positive, or negative).
212
+- StatsD increments the counter by the `INTEGER` number supplied (positive, or negative).
213
214
215
200
-#### sets
216
+#### Sets
217
218
- Scope: **count the unique occurrences of something** (e.g. unique filenames downloaded, or unique users that downloaded files)
219
- Format: `name:TEXT|s`
204
-- statsd maintains a unique index of all values supplied, and reports the unique entries in it.
220
+- StatsD maintains a unique index of all values supplied, and reports the unique entries in it.
221
222
223
208
-#### timers
224
+#### Timers
225
226
- Scope: **statistics on the duration of events** (e.g. statistics for the duration of file downloads)
227
- Format: `name:FLOAT|ms`
212
-- statsd maintains a list of all the values supplied and provides statistics on them.
228
+- StatsD maintains a list of all the values supplied and provides statistics on them.
229
230
231
232
The same chart with the `sum` unselected:
233
234
219
-### synthetic statsd charts
235
+### Synthetic StatsD charts
236
221
-Use synthetic charts to create dedicated sections on the dashboard to render the charts, with control over the main
222
-menu, the submenus, the charts, the dimensions on each chart, and more.
237
+Use synthetic charts to create dedicated sections on the dashboard to render your StatsD charts.
238
239
Synthetic charts are organized in
240
226
-- **applications** (i.e. entries at the main menu of the Netdata dashboard)
227
-- **charts for each application** (grouped in families - i.e. submenus at the dashboard menu)
228
-- **statsd metrics for each chart** (i.e. dimensions of the charts)
241
+- **application** aka section in Netdata Dashboard.
242
+- **charts for each application** aka family in Netdata Dashboard.
243
+- **StatsD metrics for each chart** /aka charts and context Netdata Dashboard.
244
+
245
+> You can read more about how the Netdata Agent organizes information in the relevant [documentation](/web/README.md)
246
247
For each application you need to create a `.conf` file in `/etc/netdata/statsd.d`.
248
232
-So, to create the statsd application `myapp`, create the file `/etc/netdata/statsd.d/myapp.conf`, with this content:
249
+For example, if you want to monitor the application `myapp` using StatD and Netdata, create the file `/etc/netdata/statsd.d/myapp.conf`, with this content:
250
251
```
252
[app]
@@ -263,11 +280,11 @@ Using the above configuration `myapp` should get its own section on the dashboar
280
`[app]` starts a new application definition. The supported settings in this section are:
281
282
- `name` defines the name of the app.
266
-- `metrics` is a Netdata simple pattern (space separated patterns, using `*` for wildcard, possibly starting with `!` for negative match). This pattern should match all the possible statsd metrics that will be participating in the application `myapp`.
283
+- `metrics` is a Netdata [simple pattern](/libnetdata/simple_pattern/README.md). This pattern should match all the possible StatsD metrics that will be participating in the application `myapp`.
284
- `private charts = yes|no`, enables or disables private charts for the metrics matched.
268
-- `gaps when not collected = yes|no`, enables or disables gaps on the charts of the application, when metrics are not collected.
269
-- `memory mode` sets the memory mode for all charts of the application. The default is the global default for Netdata (not the global default for statsd private charts).
270
-- `history` sets the size of the round robin database for this application. The default is the global default for Netdata (not the global default for statsd private charts).
285
+- `gaps when not collected = yes|no`, enables or disables gaps on the charts of the application in case that no metrics are collected.
286
+- `memory mode` sets the memory mode for all charts of the application. The default is the global default for Netdata (not the global default for StatsD private charts).
287
+- `history` sets the size of the round robin database for this application. The default is the global default for Netdata (not the global default for StatsD private charts). This is only relevant if you use `memory mode = save`. Read more on our guide: [longer metrics storage](https://learn.netdata.cloud/guides/longer-metrics-storage).
288
289
`[dictionary]` defines name-value associations. These are used to renaming metrics, when added to synthetic charts. Metric names are also defined at each `dimension` line. However, using the dictionary dimension names can be declared globally, for each app and is the only way to rename dimensions when using patterns. Of course the dictionary can be empty or missing.
290
@@ -288,13 +305,13 @@ So, the format is this:
305
dimension = [pattern] METRIC NAME TYPE MULTIPLIER DIVIDER OPTIONS
306
```
307
291
-`pattern` is a keyword. When set, `METRIC` is expected to be a Netdata simple pattern that will be used to match all the statsd metrics to be added to the chart. So, `pattern` automatically matches any number of statsd metrics, all of which will be added as separate chart dimensions.
308
+`pattern` is a keyword. When set, `METRIC` is expected to be a Netdata [simple pattern](/libnetdata/simple_pattern/README.md) that will be used to match all the StatsD metrics to be added to the chart. So, `pattern` automatically matches any number of StatsD metrics, all of which will be added as separate chart dimensions.
309
310
`TYPE`, `MULTIPLIER`, `DIVIDER` and `OPTIONS` are optional.
311
312
`TYPE` can be:
313
297
-- `events` to show the number of events received by statsd for this metric
314
+- `events` to show the number of events received by StatsD for this metric
315
- `last` to show the last value, as calculated at the flush interval of the metric (the default)
316
317
Then for histograms and timers the following types are also supported:
@@ -303,13 +320,13 @@ Then for histograms and timers the following types are also supported:
320
- `max`, show the maximum value
321
- `sum`, show the sum of all values
322
- `average` (same as `last`)
306
-- `percentile`, show the 95th percentile (or any other percentile, as configured at statsd global config)
323
+- `percentile`, show the 95th percentile (or any other percentile, as configured at StatsD global config)
324
- `median`, show the median of all values (i.e. sort all values and get the middle value)
325
- `stddev`, show the standard deviation of the values
326
310
-#### example synthetic charts
327
+#### Example synthetic charts
328
312
-statsd metrics: `foo` and `bar`.
329
+StatsD metrics: `foo` and `bar`.
330
331
Contents of file `/etc/netdata/stats.d/foobar.conf`:
332
@@ -329,17 +346,19 @@ Contents of file `/etc/netdata/stats.d/foobar.conf`:
346
dimension = bar 'bar me' last 1 1
347
```
348
332
-I sent to statsd: `foo:10|g` and `bar:20|g`.
349
+Metrics sent to statsd: `foo:10|g` and `bar:20|g`.
350
334
-I got these private charts:
351
+Private charts:
352
353
354
338
-and this synthetic chart:
355
+Synthetic chart:
356
357
358
342
-#### dictionary to name dimensions
359
+#### Renaming StatsD metrics
360
+
361
+You can define a dictionary to rename metrics sent by StatsD clients. This enables you to send response `"200"` and Netdata visualize it as `succesful connection`
362
363
The `[dictionary]` section accepts any number of `name = value` pairs.
364
@@ -347,9 +366,9 @@ Netdata uses this dictionary as follows:
366
367
1. When a `dimension` has a non-empty `NAME`, that name is looked up at the dictionary.
368
350
-2. If the above lookup gives nothing, or the `dimension` has an empty `NAME`, the original statsd metric name is looked up at the dictionary.
369
+2. If the above lookup gives nothing, or the `dimension` has an empty `NAME`, the original StatsD metric name is looked up at the dictionary.
370
352
-3. If any of the above succeeds, Netdata uses the `value` of the dictionary, to set the name of the dimension. The dimensions will have as ID the original statsd metric name, and as name, the dictionary value.
371
+3. If any of the above succeeds, Netdata uses the `value` of the dictionary, to set the name of the dimension. The dimensions will have as ID the original StatsD metric name, and as name, the dictionary value.
372
373
Use the dictionary in 2 ways:
374
@@ -358,13 +377,13 @@ Use the dictionary in 2 ways:
377
378
In both cases, the dimension will be added with ID `myapp.metric1` and will be named `metric1 name`. So, in alarms use either of the 2 as `${myapp.metric1}` or `${metric1 name}`.
379
361
-> keep in mind that if you add multiple times the same statsd metric to a chart, Netdata will append `TYPE` to the dimension ID, so `myapp.metric1` will be added as `myapp.metric1_last` or `myapp.metric1_events`, etc. If you add multiple times the same metric with the same `TYPE` to a chart, Netdata will also append an incremental counter to the dimension ID, i.e. `myapp.metric1_last1`, `myapp.metric1_last2`, etc.
380
+> keep in mind that if you add multiple times the same StatsD metric to a chart, Netdata will append `TYPE` to the dimension ID, so `myapp.metric1` will be added as `myapp.metric1_last` or `myapp.metric1_events`, etc. If you add multiple times the same metric with the same `TYPE` to a chart, Netdata will also append an incremental counter to the dimension ID, i.e. `myapp.metric1_last1`, `myapp.metric1_last2`, etc.
381
363
-#### dimension patterns
382
+#### Dimension patterns
383
365
-Netdata allows adding multiple dimensions to a chart, by matching the statsd metrics with a Netdata simple pattern.
384
+Netdata allows adding multiple dimensions to a chart, by matching the StatsD metrics with a Netdata simple pattern.
385
367
-Assume we have an API that provides statsd metrics for each response code per method it supports, like these:
386
+Assume we have an API that provides StatsD metrics for each response code per method it supports, like these:
387
388
```
389
myapp.api.get.200
@@ -381,7 +400,7 @@ myapp.api.all.400
400
myapp.api.all.500
401
```
402
384
-To add all response codes of `myapp.api.get` to a chart use this:
403
+In order to add all the response codes of `myapp.api.get` to a chart, we simply make the following configuration:
404
405
```
406
[api_get_responses]
@@ -389,7 +408,9 @@ To add all response codes of `myapp.api.get` to a chart use this:
408
dimension = pattern 'myapp.api.get.* '' last 1 1
409
```
410
392
-The above will add dimension named `200`, `400` and `500` (yes, Netdata extracts the wildcarded part of the metric name - so the dimensions will be named with whatever the `*` matched). Rename the dimensions with this:
411
+The above will add dimension named `200`, `400` and `500`. Netdata extracts the wildcard part of the metric name - so the dimensions will be named with whatever the `*` matched.
412
+
413
+You can rename the dimensions with this:
414
415
```
416
[dictionary]
@@ -404,7 +425,7 @@ The above will add dimension named `200`, `400` and `500` (yes, Netdata extracts
425
426
Note that we added a `NAME` to the dimension line with `get.`. This is prefixed to the wildcarded part of the metric name, to compose the key for looking up the dictionary. So `500` became `get.500` which was looked up to the dictionary to find value `500 cannot connect to db`. This way we can have different dimension names, for each of the API methods (i.e. `get.500 = 500 cannot connect to db` while `post.500 = 500 cannot write to disk`).
427
407
-To add all API methods to a chart, do this:
428
+To add all API methods to a chart, you can do this:
429
430
```
431
[ok_by_method]
@@ -424,7 +445,7 @@ If `all` is not wanted (a `stacked` chart does not need the `all` dimension, sin
445
446
With the above, all methods except `all` will be added to the chart.
447
427
-To automatically rename the methods, use this:
448
+To automatically rename the methods, you can use this:
449
450
```
451
[dictionary]
@@ -439,20 +460,73 @@ To automatically rename the methods, use this:
460
461
Using the above, the dimensions will be added as `GET`, `ADD` and `DELETE`.
462
442
-## interpolation
463
+## StatsD examples
464
444
-~~If you send just one value to statsd, you will notice that the chart is created but no value is shown. The reason is that Netdata interpolates all values at second boundaries. For incremental values (`counters` and `meters` in statsd terminology), if you send 10 at 00:00:00.500, 20 at 00:00:01.500 and 30 at 00:00:02.500, Netdata will show 15 at 00:00:01 and 25 at 00:00:02.~~
465
+### Python
466
+
467
+It's really easy to instrument your python application with StatsD, for example using [jsocol/pystatsd](https://github.com/jsocol/pystatsd).
468
+
469
+```python
470
+import statsd
471
+c = statsd.StatsClient('localhost', 8125)
472
+c.incr('foo') # Increment the 'foo' counter.
473
+for i in range(100000000):
474
+ c.incr('bar')
475
+ c.incr('foo')
476
+ if i % 3:
477
+ c.decr('bar')
478
+ c.timing('stats.timed', 320) # Record a 320ms 'stats.timed'.
479
+```
480
446
-~~This interpolation is automatic and global in Netdata for all charts, for incremental values. This means that for the chart to start showing values you need to send 2 values across 2 flush intervals.~~
481
+You can find detailed documentation in their [documentation page](https://statsd.readthedocs.io/en/v3.3/).
482
448
-~~(although this is required for incremental values, Netdata allows mixing incremental and absolute values on the same charts, so this little limitation [i.e. 2 values to start visualization], is applied on all Netdata dimensions).~~
483
+### Javascript and Node.js
484
450
-(statsd metrics do not lose their first data collection due to interpolation anymore - fixed with [PR #2411](https://github.com/netdata/netdata/pull/2411))
485
+Using the client library by [sivy/node-statsd](https://github.com/sivy/node-statsd), you can easily embed StatsD into your Node.js project.
486
452
-## sending statsd metrics from shell scripts
487
+```javascript
488
+ var StatsD = require('node-statsd'),
489
+ client = new StatsD();
490
454
-Send/update statsd metrics from shell scripts to visualize automated jobs you run on your servers using the Netdata
455
-Agent.
491
+ // Timing: sends a timing command with the specified milliseconds
492
+ client.timing('response_time', 42);
493
+
494
+ // Increment: Increments a stat by a value (default is 1)
495
+ client.increment('my_counter');
496
+
497
+ // Decrement: Decrements a stat by a value (default is -1)
498
+ client.decrement('my_counter');
499
+
500
+ // Using the callback
501
+ client.set(['foo', 'bar'], 42, function(error, bytes){
502
+ //this only gets called once after all messages have been sent
503
+ if(error){
504
+ console.error('Oh noes! There was an error:', error);
505
+ } else {
506
+ console.log('Successfully sent', bytes, 'bytes');
507
+ }
508
+ });
509
+
510
+ // Sampling, tags and callback are optional and could be used in any combination
511
+ client.histogram('my_histogram', 42, 0.25); // 25% Sample Rate
512
+ client.histogram('my_histogram', 42, ['tag']); // User-defined tag
513
+ client.histogram('my_histogram', 42, next); // Callback
514
+ client.histogram('my_histogram', 42, 0.25, ['tag']);
515
+ client.histogram('my_histogram', 42, 0.25, next);
516
+ client.histogram('my_histogram', 42, ['tag'], next);
517
+ client.histogram('my_histogram', 42, 0.25, ['tag'], next);
518
+```
519
+### Other languages
520
+
521
+You can also use StatsD with:
522
+- Golang, thanks to [alexcesaro/statsd](https://github.com/alexcesaro/statsd)
523
+- Ruby, thanks to [reinh/statsd](https://github.com/reinh/statsd)
524
+- Java, thanks to [DataDog/java-docstatsd-client](https://github.com/DataDog/java-dogstatsd-client)
525
+
526
+
527
+### Shell
528
+
529
+Getting the proper support for a programming language is not always easy, but shell is always available on most UNIX systems. You can use shell and `nc` to easily instrument your systems and send metric data to Netdata StatsD. Here is how:
530
531
The command you need to run is:
532
@@ -522,9 +596,10 @@ You can use it like this:
596
source statsd.sh
597
598
# then, at any point:
525
-statsd "metric1:10|g" "metric2:10|c" ...
599
+StatsD "metric1:10|g" "metric2:10|c" ...
600
```
527
-
601
The function is smart enough to call `nc` just once and pass all the metrics to it. It will also automatically switch to TCP if the metrics to send are above 1000 bytes.
602
603
+If you have gotten thus far, make sure to check out our [Community Forums](https://community.netdata.cloud) to share your experience using Netdata with StatsD.
604
+
605
[](<>)
web/gui/dashboard_info.js
+5
-1
@@ -582,7 +582,11 @@ netdataDashboard.menu = {
582
icon: '<i class="fas fa-bell"></i>',
583
info: 'Charts showing alarm status over time. More details <a href="https://github.com/netdata/netdata/blob/master/collectors/python.d.plugin/alarms/README.md" target="_blank">here</a>.'
584
},
585
-
585
+ 'statsd': {
586
+ title: 'StatsD',
587
+ icon: '<i class="fas fa-chart-line"></i>',
588
+ info:'StatsD is an industry-standard technology stack for monitoring applications and instrumenting any piece of software to deliver custom metrics. Netdata allows the user to organize the metrics in different charts and visualize any application metric easily. Read more on <a href="https://learn.netdata.cloud/docs/agent/collectors/statsd.plugin">Netdata Learn</a>.'
589
+ }
590
};
591
592