@cryptotaxi247 / netdata-1 / commits / 5c8d4dd1a

Improved StatsD documentation (#20282)

Co-authored-by: ilyam8 <ilya@netdata.cloud>

kanelatechnical committed May 14, 2025 at 21:29 UTC 5c8d4dd1aa60e2928fcb234813d7cadd2ca128ca
1 file changed +532 -555
src/collectors/statsd.plugin/README.md
+532 -555
@@ -1,161 +1,257 @@
1 -# StatsD
1 +# StatsD Collector
2
3 -[StatsD](https://github.com/statsd/statsd) is a system to collect data from any application. Applications send metrics to it,
4 -usually via non-blocking UDP communication, and StatsD servers collect these metrics, perform a few simple calculations on
5 -them and push them to backend time-series databases.
3 +## What is StatsD?
4
7 -If you want to learn more about the StatsD protocol, we have written a
8 -[blog post](https://blog.netdata.cloud/introduction-to-statsd/) about it!
5 +[StatsD](https://github.com/statsd/statsd) is a system for collecting metrics from applications. Your applications send metrics to StatsD, usually via non-blocking UDP communication, and StatsD servers collect these metrics, perform simple calculations, and push them to time-series databases.
6
7 +Learn more about the [StatsD protocol.](https://blog.netdata.cloud/introduction-to-statsd/)
8
11 -Netdata is a fully featured statsd server. It can collect statsd formatted metrics, visualize
12 -them on its dashboards and store them in it's database for long-term retention.
9 +## Overview
10
14 -Netdata statsd is inside Netdata (an internal plugin, running inside the Netdata daemon), it is
15 -configured via `netdata.conf` and by-default listens on standard statsd port 8125. Netdata supports
16 -both TCP and UDP packets at the same time.
11 +| Feature | Description |
12 +|----------------------------|----------------------------------------------------------------------------|
13 +| **Metric Collection** | Collect real-time metrics from any application supporting StatsD protocol |
14 +| **Visualization** | View metrics as private charts (one per metric) or custom synthetic charts |
15 +| **Supported Metric Types** | Gauges, Counters, Meters, Timers, Histograms, Sets, Dictionaries |
16 +| **Transport** | Both UDP (low-overhead) and TCP (reliable, higher volume) supported |
17 +| **Performance** | Can collect millions of metrics per second using just 1 CPU core |
18 +| **Integration** | Built directly into Netdata - no extra installation needed |
19 +| **Language Support** | Use with Python, Node.js, Java, Go, Ruby, Shell scripts, and more |
20
18 -Since statsd is embedded in Netdata, it means you now have a statsd server embedded on all your servers.
21 +:::tip
22
20 -Netdata statsd is fast. It can collect several millions of metrics per second on modern hardware, using
21 -just 1 CPU core. The implementation uses two threads: one thread collects metrics, another thread updates
22 -the charts from the collected data.
23 +Want a hands-on example? [Jump to the K6 StatsD Walkthrough](#step-by-step-guide-monitoring-k6-with-statsd)
24
24 -## Available StatsD synthetic application charts
25 +:::
26
26 -Netdata ships with a few synthetic chart definitions to automatically present application metrics into a
27 -more uniform way. These synthetic charts are configuration files (you can create your own) that re-arrange
28 -statsd metrics into a more meaningful way.
27 +## Supported Metric Types Summary
28
30 -On synthetic charts, we can have alerts as with any metric and chart.
29 +| Metric Type | Purpose | Format | LLM Summary |
30 +|--------------|-----------------------------------------------|---------------------|-------------------------------------------------------------------------------------------------|
31 +| Gauges | Report current values | `name:value\|g` | Report latest value; can increment/decrement; supports sampling & tags. |
32 +| Counters | Count events | `name:value\|c/C/m` | Report rate & event count; `:value` optional (default 1); supports sampling & tags. |
33 +| Meters | Count events (rate-focused) | `name:value\|m` | Report rate & event count; `:value` optional (default 1); supports sampling & tags. |
34 +| Timers | Statistical analysis of values (duration) | `name:value\|ms` | Report min, max, avg, percentiles, median, stddev, count; supports sampling & tags. |
35 +| Histograms | Statistical analysis of values (distribution) | `name:value\|h` | Report min, max, avg, percentiles, median, stddev, count; supports sampling & tags. |
36 +| Sets | Count unique occurrences | `name:value\|s` | Report unique count & event count; sampling NOT supported; values as text; supports tags. |
37 +| Dictionaries | Count occurrences of distinct values | `name:value\|d` | Report counts per value & total updates; sampling NOT supported; values as text; supports tags. |
38
32 -- [K6 load testing tool](https://k6.io)
33 - - **Description:** k6 is a developer-centric, free and open-source load testing tool built for making performance testing a productive and enjoyable experience.
34 - - [Documentation](/src/collectors/statsd.plugin/k6.md)
35 - - [Configuration](https://github.com/netdata/netdata/blob/master/src/collectors/statsd.plugin/k6.conf)
36 -- [Asterisk](https://www.asterisk.org/)
37 - - **Description:** Asterisk is an Open Source PBX and telephony toolkit.
38 - - [Documentation](/src/collectors/statsd.plugin/asterisk.md)
39 - - [Configuration](https://github.com/netdata/netdata/blob/master/src/collectors/statsd.plugin/asterisk.conf)
39 +### How StatsD Works with Netdata
40 +
41 +```mermaid
42 +graph TD
43 + A[Your Application] -->|Sends metrics| B[Netdata StatsD]
44 + B -->|Creates| C[Private Charts]
45 + B -->|Creates| D[Synthetic Charts]
46 + B -->|Stores in| E[Database]
47 +
48 + style A fill:#f9f9f9,stroke:#333,stroke-width:1px
49 + style B fill:#4caf50,stroke:#333,stroke-width:1px,color:black
50 + style C fill:#4caf50,stroke:#333,stroke-width:1px,color:black
51 + style D fill:#4caf50,stroke:#333,stroke-width:1px,color:black
52 + style E fill:#4caf50,stroke:#333,stroke-width:1px,color:black
53 +```
54 +
55 +## Netdata as a StatsD Server
56 +
57 +Netdata comes with a **fully-featured StatsD server built in**. You can:
58 +
59 +- Collect StatsD-formatted metrics
60 +- Visualize them on the Netdata dashboard
61 +- Store them in Netdata's database for long-term retention
62 +
63 +Since StatsD is embedded in Netdata, **you effectively have a StatsD server on every system where Netdata is installed.**
64
41 -## Metrics supported by Netdata
65 +:::note
66
43 -Netdata fully supports the StatsD protocol and also extends it to support more advanced Netdata specific use cases.
44 -All StatsD client libraries can be used with Netdata too.
67 +**Netdata's StatsD implementation is incredibly fast.** It can collect **several million metrics per second** on modern hardware using just one CPU core. The implementation uses two threads: one collects metrics, and the other updates the charts.
68
46 -- **Gauges**
69 +:::
70
48 - The application sends `name:value|g`, where `value` is any **decimal/fractional** number, StatsD reports the
49 - latest value collected and the number of times it was updated (events).
71 +## Pre-configured StatsD Applications
72
51 - The application may increment or decrement a previous value, by setting the first character of the value to
52 - `+` or `-` (so, the only way to set a gauge to an absolute negative value, is to first set it to zero).
73 +Netdata includes **synthetic chart definitions** to automatically present application metrics consistently. These are defined in configuration files that you can use as-is or customize.
74
54 - [Sampling rate](#sampling-rates) is supported.
55 - [Tags](#tags) are supported for changing chart units, family and dimension name.
75 +For synthetic charts, you can set up alerts just like with any other metric or chart.
76
57 - 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.
77 +Currently available applications:
78
59 -- **Counters** and **Meters**
79 +- [K6 load testing tool](https://k6.io)
80 + - **Description:** k6 is a developer-centric, free, and open-source load testing tool for performance testing
81 + - [Documentation](https://github.com/netdata/netdata/blob/master/src/collectors/statsd.plugin/k6.md)
82 + - [Configuration](https://github.com/netdata/netdata/blob/master/src/collectors/statsd.plugin/k6.conf)
83 +- [Asterisk](https://www.asterisk.org/)
84 + - **Description:** Asterisk is an Open Source PBX and telephony toolkit
85 + - [Documentation](https://github.com/netdata/netdata/blob/master/src/collectors/statsd.plugin/asterisk.md)
86 + - [Configuration](https://github.com/netdata/netdata/blob/master/src/collectors/statsd.plugin/asterisk.conf)
87 +
88 +## Supported Metric Types
89 +
90 +Netdata fully supports the StatsD protocol and extends it for more advanced use cases. All StatsD client libraries are compatible with Netdata.
91 +
92 +```mermaid
93 +graph TD
94 + A[Application] -->|Sends| B[Metrics]
95 + B --> C[Gauges]
96 + B --> D[Counters]
97 + B --> E[Timers]
98 + B --> F[Histograms]
99 + B --> G[Sets]
100 + B --> H[Dictionaries]
101 +
102 + style A fill:#f9f9f9,stroke:#333,stroke-width:1px
103 + style B fill:#4caf50,stroke:#333,stroke-width:1px,color:black
104 + style C fill:#4caf50,stroke:#333,stroke-width:1px,color:black
105 + style D fill:#4caf50,stroke:#333,stroke-width:1px,color:black
106 + style E fill:#4caf50,stroke:#333,stroke-width:1px,color:black
107 + style F fill:#4caf50,stroke:#333,stroke-width:1px,color:black
108 + style G fill:#4caf50,stroke:#333,stroke-width:1px,color:black
109 + style H fill:#4caf50,stroke:#333,stroke-width:1px,color:black
110 +```
111 +
112 +<details>
113 +<summary><strong>Gauges</strong></summary>
114 +<br/>
115
61 - The application sends `name:value|c`, `name:value|C` or `name:value|m`, where `value` is a positive or negative **integer** number of events occurred, StatsD reports the **rate** and the number of times it was updated (events).
116 +<strong>Purpose:</strong> Report current values (e.g., cache memory used by an application server)
117
63 - `:value` can be omitted and StatsD will assume it is `1`. `|c`, `|C` and `|m` can be omitted and StatsD will assume it is `|m`. So, the application may send just `name` and StatsD will parse it as `name:1|m`.
118 +**Format:** `name:value|g`
119
65 - - Counters use `|c` (etsy/StatsD compatible) or `|C` (brubeck compatible)
66 - - Meters use `|m`
120 +- `value` can be any decimal/fractional number
121 +- StatsD reports the latest value and the number of updates (events)
122 +- You can increment/decrement previous values by prefixing with `+` or `-`
123 +- Sampling rate is supported
124 +- Tags can change chart units, family, and [dimension](https://learn.netdata.cloud/docs/developer-and-contributor-corner/glossary#d) name
125 +- When not collected, the last value will be shown if "show gaps" is disabled (default)
126
68 - [Sampling rate](#sampling-rates) is supported.
69 - [Tags](#tags) are supported for changing chart units, family and dimension name.
127 +</details>
128
71 - When a counter or meter is not collected, StatsD **defaults** to showing a zero value, until a data collection event changes the value.
72 -
73 -- **Timers** and **Histograms**
129 +<details>
130 +<summary><strong>Counters and Meters</strong></summary>
131 +<br/>
132
75 - The application sends `name:value|ms` or `name:value|h`, where `value` is any **decimal/fractional** number, StatsD reports **min**, **max**, **average**, **95th percentile**, **median** and **standard deviation** and the total number of times it was updated (events). Internally it also calculates the **sum**, which is available for synthetic charts.
133 +<strong>Purpose:</strong> Count events (e.g., number of file downloads)
134
77 - - Timers use `|ms`
78 - - Histograms use `|h`
79 -
80 - The only difference between the two, is the `units` of the charts, as timers report *milliseconds*.
135 +**Format:** `name:value|c`, `name:value|C`, or `name:value|m`
136
82 - [Sampling rate](#sampling-rates) is supported.
83 - [Tags](#tags) are supported for changing chart units and family.
137 +- `value` must be an integer (positive or negative)
138 +- StatsD reports the rate and update count (events)
139 +- `:value` can be omitted (defaults to 1)
140 +- `|c`, `|C` and `|m` can be omitted (defaults to `|m`)
141 +- Counters use `|c` (etsy/StatsD compatible) or `|C` (brubeck compatible)
142 +- Meters use `|m`
143 +- Sampling rate is supported
144 +- Tags can change chart units, family, and dimension name
145 +- When not collected, StatsD shows zero until a new value arrives
146
85 - When a counter or meter is not collected, StatsD **defaults** to showing a zero value, until a data collection event changes the value.
147 +</details>
148
87 -- **Sets**
149 +<details>
150 +<summary><strong>Timers and Histograms</strong></summary>
151 +<br/>
152
89 - The application sends `name:value|s`, where `value` is anything (**number or text**, leading and trailing spaces are removed), StatsD reports the number of unique values sent and the number of times it was updated (events).
153 +<strong>Purpose:</strong> Statistical analysis of values (e.g., request duration, file sizes)
154
91 - Sampling rate is **not** supported for Sets. `value` is always considered text (so `01` and `1` are considered different).
155 +**Format:** `name:value|ms` or `name:value|h`
156
93 - [Tags](#tags) are supported for changing chart units and family.
157 +- `value` can be any decimal/fractional number
158 +- StatsD reports min, max, average, 95th percentile, median, standard deviation, and update count
159 +- Timers use `|ms` and report in milliseconds
160 +- Histograms use `|h`
161 +- Sampling rate is supported
162 +- Tags can change chart units and family
163 +- When not collected, StatsD shows zero until a new value arrives
164
95 - When a set is not collected, Netdata **defaults** to showing a zero value, until a data collection event changes the value.
165 +</details>
166
97 -- **Dictionaries**
167 +<details>
168 +<summary><strong>Sets</strong></summary>
169 +<br/>
170
99 - The application sends `name:value|d`, where `value` is anything (**number or text**, leading and trailing spaces are removed), StatsD reports the number of events sent for each `value` and the total times `name` was updated (events).
171 +<strong>Purpose:</strong> Count unique occurrences (e.g., unique users, unique filenames)
172
101 - Sampling rate is **not** supported for Dictionaries. `value` is always considered text (so `01` and `1` are considered different).
173 +**Format:** `name:value|s`
174
103 - [Tags](#tags) are supported for changing chart units and family.
175 +- `value` can be any string or number (leading/trailing spaces are removed)
176 +- StatsD reports the count of unique values and update count
177 +- Sampling rate is NOT supported
178 +- Values are always treated as text (so `01` and `1` are different)
179 +- Tags can change chart units and family
180 +- When not collected, StatsD shows zero until a new value arrives
181
105 - When a set is not collected, Netdata **defaults** to showing a zero value, until a data collection event changes the value.
182 +</details>
183
107 -#### Sampling Rates
184 +<details>
185 +<summary><strong>Dictionaries</strong></summary>
186 +<br/>
187
109 -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.
188 +<strong>Purpose:</strong> Count occurrences of distinct values
189
111 -#### Tags
190 +**Format:** `name:value|d`
191
113 -The application may append `|#tag1:value1,tag2:value2,tag3:value3` etc, where `tagX` and `valueX` are strings. `:valueX` can be omitted.
192 +- `value` can be any string or number (leading/trailing spaces are removed)
193 +- StatsD reports the count of events for each `value` and total updates
194 +- Sampling rate is NOT supported
195 +- Values are always treated as text (so `01` and `1` are different)
196 +- Tags can change chart units and family
197 +- When not collected, StatsD shows zero until a new value arrives
198
115 -Currently, Netdata uses only 2 tags:
199 +</details>
200
117 - * `units=string` which sets the units of the chart that is automatically generated
118 - * `family=string` which sets the family of the chart that is automatically generated (the family is the submenu of the dashboard)
119 - * `name=string` which sets the name of the dimension of the chart that is automatically generated (only for counters, meters, gauges)
201 +## Advanced Features
202
121 -Other tags are parsed, but currently are ignored.
203 +<details>
204 +<summary><strong>Sampling Rates</strong></summary>
205 +<br/>
206
123 -Charts are not updated to change units or dimension names once they are created. So, either send the tags on every event, or use the special `zinit` value to initiaze the charts at the beginning. `zinit` is a special value that can be used on any chart, to have netdata initialize the charts, without actually setting any values to them. So, instead of sending `my.metric:VALUE|c|#units=bytes,name=size` every time, the application can send at the beginning `my.metric:zinit|c|#units=bytes,name=size` and then `my.metric:VALUE|c`.
207 +You can append `|@sampling_rate` to metrics, where `sampling_rate` is between 0.0 and 1.0. This tells StatsD to extrapolate the value for the entire period.
208
125 -#### Overlapping metrics
209 +Example: If your application reports data for only 1/10th of events, append `|@0.1` to have StatsD calculate the total.
210 +</details>
211
127 -Netdata's StatsD server maintains different indexes for each of the metric types supported. This means the same metric `name` may exist under different types concurrently.
212 +<details>
213 +<summary><strong>Tags</strong></summary>
214 +<br/>
215
129 -#### How to name your metrics
216 +You can append `|#tag1:value1,tag2:value2,tag3:value3` to metrics. Netdata currently uses these tags:
217
131 -A good practice is to name your metrics like `application.operation.metric`, where:
218 +- `units=string` - Sets the units of the automatically generated chart
219 +- `family=string` - Sets the family (dashboard submenu) of the chart
220 +- `name=string` - Sets the [dimension](https://learn.netdata.cloud/docs/developer-and-contributor-corner/glossary#d) name (for counters, meters, gauges only)
221
133 -- `application` is the application name - Netdata will automatically create a dashboard section based on the first keyword of the metrics, so you can have all your applications in different sections.
134 -- `operation` is the operation your application is executing, like `dbquery`, `request`, `response`, etc.
135 -- `metric` is anything you want to name your metric as. Netdata will automatically append the metric type (meter, counter, gauge, set, dictionary, timer, histogram) to the generated chart.
222 +:::tip
223
137 -Using [Tags](#tags) you can also change the submenus of the dashboard, the units of the charts and for meters, counters and gauges, the name of dimension. So, you can have a usable default view without using [Synthetic StatsD charts](#synthetic-statsd-charts)
224 +For consistency, either send tags with every event or use the special `zinit` value to initialize charts. For example, send `my.metric:zinit|c|#units=bytes,name=size` at the beginning, then just `my.metric:VALUE|c` afterward.
225
139 -#### Multiple metrics per packet
226 +:::
227
141 -Netdata accepts multiple metrics per packet if each is terminated with a newline (`\n`) at the end.
228 +</details>
229
143 -#### TCP packets
230 +<details>
231 +<summary><strong>Sending Multiple Metrics</strong></summary>
232 +<br/>
233
145 -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.
234 +You can send multiple metrics in a single packet by separating them with newlines (`\n`).
235
236 +#### TCP Packets
237
148 -#### UDP packets
238 +Netdata listens for both TCP and UDP packets. With TCP, always append `\n` to each metric so Netdata can detect metrics split across multiple TCP packets.
239
150 -When sending multiple metrics over a single UDP message, it is important not to exceed the network MTU, which is usually 1500 bytes.
240 +#### UDP Packets
241
152 -Netdata will accept UDP packets up to 9000 bytes, but the underlying network will not exceed MTU.
242 +When sending multiple metrics in a UDP message, keep the total size under the network MTU (usually 1500 bytes).
243
154 -> You can read more about the network maximum transmission unit(MTU) in this cloudflare [article](https://www.cloudflare.com/en-gb/learning/network-layer/what-is-mtu/).
244 +:::important
245 +
246 +Netdata will accept UDP packets up to 9000 bytes, but your network equipment may fragment any packets exceeding the MTU.
247 +
248 +:::
249 +
250 +</details>
251
252 ## Configuration
253
158 -You can find the configuration at `/etc/netdata/netdata.conf`:
254 +You can find the StatsD configuration in `/etc/netdata/netdata.conf`:
255
256 ```
257 [statsd]
@@ -181,126 +277,140 @@ You can find the configuration at `/etc/netdata/netdata.conf`:
277 # bind to = udp:localhost:8125 tcp:localhost:8125
278 ```
279
184 -### StatsD main config options
185 -
186 -- `enabled = yes|no`
280 +## Configuration Architecture
281
188 - controls if StatsD will be enabled for this Netdata. The default is enabled.
282 +### How the StatsD Configuration Works
283
190 -- `default port = 8125`
284 +Netdata's StatsD chart system uses three key sections in its configuration:
285
192 - controls the default port StatsD will use if no port is defined in the following setting.
286 +```mermaid
287 +graph TD
288 + A[[statsd.d config]] --> B[app]
289 + A --> C[dictionary]
290 + A --> D[chart definitions]
291 + B --> E[metric filtering]
292 + C --> F[renaming for display]
293 + D --> G[chart family/context/units/priorities]
294 +
295 + classDef default fill:#4caf50,stroke:#333,stroke-width:1px,color:black
296 + classDef config fill:#f9f9f9,stroke:#333,stroke-width:1px
297 +
298 + class A config
299 + class B,C,D,E,F,G default
300 +```
301
194 -- `bind to = udp:localhost tcp:localhost`
302 +The diagram shows how the configuration flows:
303
196 - 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.
304 +1. The central `statsd.d config` connects to **three main components**:
305 + - The **application** configuration
306 + - The **dictionary** system
307 + - **Chart definitions**
308
198 -- `update every (flushInterval) = 1s` controls the frequency StatsD will push the collected metrics to Netdata charts.
309 +2. Each of these components serves a specific purpose:
310 + - The **app** component handles **metric filtering**
311 + - The **dictionary** manages **renaming metrics** for display
312 + - **Chart definitions determine properties** like family, context, units, and priorities
313
200 -- `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).
314 +This structure allows for flexible and powerful metric configuration within Netdata's StatsD implementation.
315
202 -The rest of the settings are discussed below.
316 +### Key Configuration Options
317
204 -## StatsD charts
318 +- **`enabled = yes|no`** - Controls whether StatsD is enabled
319 +- **`default port = 8125`** - The default port if not specified in binding
320 +- **`bind to = udp:localhost tcp:localhost`** - Space-separated list of IPs and ports to listen on
321 +- **`update every (flushInterval) = 1s`** - How often StatsD updates Netdata charts
322 +- **`decimal detail = 1000`** - Controls decimal precision in gauges and histograms
323
206 -Netdata can visualize StatsD collected metrics in 2 ways:
324 +## StatsD Charts
325
208 -1. Each metric gets its own **private chart**. This is the default and does not require any configuration. You can adjust the default parameters.
326 +Netdata can visualize StatsD collected metrics in two ways:
327
210 -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.
328 +1. **Private charts** - Each metric gets its own chart (default, no configuration needed)
329 +2. **Synthetic charts** - Combine multiple metrics into custom charts (requires configuration)
330
212 -### Private metric charts
331 +### Private Metric Charts
332
214 -Private charts are controlled with `create private charts for metrics matching = *`. This setting accepts a space-separated list of [simple patterns](/src/libnetdata/simple_pattern/README.md). Netdata will create private charts for all metrics **by default**.
333 +Private charts are controlled with `create private charts for metrics matching = *`. This setting accepts a space-separated list of [simple patterns](https://github.com/netdata/netdata/blob/master/src/libnetdata/simple_pattern/README.md). By default, Netdata creates private charts for all metrics.
334
216 -For example, to render charts for all `myapp.*` metrics, except `myapp.*.badmetric`, use:
335 +Example: To create charts for all `myapp.*` metrics except `myapp.*.badmetric`:
336
337 ```
338 create private charts for metrics matching = !myapp.*.badmetric myapp.*
339 ```
340
222 -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](/src/database/README.md).
341 +You can configure a different memory mode specifically for StatsD charts:
342
224 -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:
343 - `private charts memory mode`
344 - `private charts history`
345
228 -### Optimize private metric charts storage
229 -
230 -For optimization reasons, Netdata imposes a hard limit on private metric charts. The limit is set via the `max private charts hard limit` setting (which defaults to 1000 charts). Metrics above this hard limit are still collected, but they can only be used in synthetic charts (once a metric is added to chart, it will be sent to backend servers too).
231 -
232 -If you have many ephemeral metrics collected (i.e. that you collect values for a certain amount of time), you can set the configuration option `set charts as obsolete after`. Setting a value in seconds here, means that Netdata will mark those metrics (and their private charts) as obsolete after the specified time has passed since the last sent metric value. Those charts will later be deleted according to the setting in `cleanup obsolete charts after`. Setting `set charts as obsolete after` to 0 (which is also the default value) will disable this functionality.
346 +<details>
347 +<summary><strong>Private Chart Examples</strong></summary>
348 +<br/>
349
234 -Example private charts (automatically generated without any configuration):
350 +Example of a gauge metric chart:
351
236 -#### Counters
237 -
238 -- Scope: **count the events of something** (e.g. number of file downloads)
239 -- Format: `name:INTEGER|c` or `name:INTEGER|C` or `name|c`
240 -- StatsD increments the counter by the `INTEGER` number supplied (positive, or negative).
241 -
242 -![image](https://cloud.githubusercontent.com/assets/2662304/26131553/4a26d19c-3aa3-11e7-94e8-c53b5ed6ebc3.png)
243 -
244 -#### Gauges
352 +![Gauge metric example](https://i.imgur.com/Sr5nJEV.png)
353
246 -- Scope: **report the value of something** (e.g. cache memory used by the application server)
247 -- Format: `name:FLOAT|g`
248 -- StatsD remembers the last value supplied, and can increment or decrement the latest value if `FLOAT` begins with `+` or `-`.
354 +Example of a histogram metric chart:
355
250 -![image](https://cloud.githubusercontent.com/assets/2662304/26131575/5d54e6f0-3aa3-11e7-9099-bc4440cd4592.png)
356 +![Timer metric example](https://i.imgur.com/P4p0hvq.png)
357
252 -#### histograms
358 +Histogram chart with "sum" unselected:
359
254 -- Scope: **statistics on a size of events** (e.g. statistics on the sizes of files downloaded)
255 -- Format: `name:FLOAT|h`
256 -- StatsD maintains a list of all the values supplied and provides statistics on them.
360 +![Histogram dimensions](https://cloud.githubusercontent.com/assets/2662304/26131598/8076443a-3aa3-11e7-9ffa-ea535aee9c9f.png)
361
258 -![image](https://cloud.githubusercontent.com/assets/2662304/26131587/704de72a-3aa3-11e7-9ea9-0d2bb778c150.png)
362 +Example of a counter metric chart:
363
260 -The same chart with `sum` unselected, to show the detail of the dimensions supported:
261 -![image](https://cloud.githubusercontent.com/assets/2662304/26131598/8076443a-3aa3-11e7-9ffa-ea535aee9c9f.png)
364 +![Counter example](https://cloud.githubusercontent.com/assets/2662304/26131553/4a26d19c-3aa3-11e7-94e8-c53b5ed6ebc3.png)
365
263 -#### Meters
366 +Example of a meter metric chart:
367
265 -This is identical to `counter`.
368 +![Meter example](https://cloud.githubusercontent.com/assets/2662304/26131605/8fdf5a06-3aa3-11e7-963f-7ecf207d1dbc.png)
369
267 -- Scope: **count the events of something** (e.g. number of file downloads)
268 -- Format: `name:INTEGER|m` or `name|m` or just `name`
269 -- StatsD increments the counter by the `INTEGER` number supplied (positive, or negative).
370 +Example of a set metric chart:
371
271 -![image](https://cloud.githubusercontent.com/assets/2662304/26131605/8fdf5a06-3aa3-11e7-963f-7ecf207d1dbc.png)
372 +![Set example](https://cloud.githubusercontent.com/assets/2662304/26131612/9eaa7b1a-3aa3-11e7-903b-d881e9a35be2.png)
373
273 -#### Sets
374 +Example of a timer metric chart:
375
275 -- Scope: **count the unique occurrences of something** (e.g. unique filenames downloaded, or unique users that downloaded files)
276 -- Format: `name:TEXT|s`
277 -- StatsD maintains a unique index of all values supplied, and reports the unique entries in it.
376 +![Timer example](https://cloud.githubusercontent.com/assets/2662304/26131629/bc34f2d2-3aa3-11e7-8a07-f2fc94ba4352.png)
377 +</details>
378
279 -![image](https://cloud.githubusercontent.com/assets/2662304/26131612/9eaa7b1a-3aa3-11e7-903b-d881e9a35be2.png)
379 +#### Storage Optimization
380
281 -#### Timers
381 +For performance reasons, Netdata limits private charts. The `max private charts hard limit` (default: 1000) controls this. Metrics above this limit can still be used in synthetic charts.
382
283 -- Scope: **statistics on the duration of events** (e.g. statistics for the duration of file downloads)
284 -- Format: `name:FLOAT|ms`
285 -- StatsD maintains a list of all the values supplied and provides statistics on them.
383 +For ephemeral metrics, use `set charts as obsolete after` and `cleanup obsolete charts after` to automatically clean up charts that haven't received data recently.
384
287 -![image](https://cloud.githubusercontent.com/assets/2662304/26131629/bc34f2d2-3aa3-11e7-8a07-f2fc94ba4352.png)
385 +### Synthetic StatsD Charts
386
289 -### Synthetic StatsD charts
387 +Use synthetic charts to create dedicated sections on the dashboard to render your StatsD charts.
388
291 -Use synthetic charts to create dedicated sections on the dashboard to render your StatsD charts.
389 +```mermaid
390 +graph TD
391 + A[StatsD Metrics] --> B[App]
392 + A --> C[Dictionary]
393 + B --> D[Chart]
394 + C --> D
395 + D --> E[Dashboard]
396 +
397 + style A fill:#f9f9f9,stroke:#333,stroke-width:1px
398 + style B fill:#4caf50,stroke:#333,stroke-width:1px,color:black
399 + style C fill:#4caf50,stroke:#333,stroke-width:1px,color:black
400 + style D fill:#4caf50,stroke:#333,stroke-width:1px,color:black
401 + style E fill:#4caf50,stroke:#333,stroke-width:1px,color:black
402 +```
403
293 -Synthetic charts are organized in
404 +Synthetic charts are organized in:
405
295 -- **application** aka section in Netdata Dashboard.
296 -- **charts for each application** aka family in Netdata Dashboard.
297 -- **StatsD metrics for each chart** /aka charts and context Netdata Dashboard.
406 +- **Application** - Section in Netdata Dashboard
407 +- **Charts for each application** - Family/submenu in the Dashboard
408 +- **StatsD metrics for each chart** - Charts and context in the Dashboard
409
299 -> You can read more about how the Netdata Agent organizes information in the relevant [documentation](/src/web/README.md)
410 +#### Basic Configuration Structure
411
301 -For each application you need to create a `.conf` file in `/etc/netdata/statsd.d`.
412 +For example, to monitor the application `myapp` using StatsD and Netdata, create the file `/etc/netdata/statsd.d/myapp.conf`:
413
303 -For example, if you want to monitor the application `myapp` using StatsD and Netdata, create the file `/etc/netdata/statsd.d/myapp.conf`, with this content:
414 ```
415 [app]
416 name = myapp
@@ -313,8 +423,8 @@ For example, if you want to monitor the application `myapp` using StatsD and Net
423 m1 = metric1
424 m2 = metric2
425
316 -# replace 'mychart' with the chart id
317 -# the chart will be named: myapp.mychart
426 +# Chart definition with ID 'mychart'
427 +# The chart will be named: myapp.mychart
428 [mychart]
429 name = mychart
430 title = my chart title
@@ -327,116 +437,113 @@ For example, if you want to monitor the application `myapp` using StatsD and Net
437 dimension = myapp.metric2 m2
438 ```
439
330 -Using the above configuration `myapp` should get its own section on the dashboard, having one chart with 2 dimensions.
440 +Using this configuration, `myapp` gets its own dashboard section with one chart containing two [dimensions](https://learn.netdata.cloud/docs/developer-and-contributor-corner/glossary#d).
441
332 -`[app]` starts a new application definition. The supported settings in this section are:
442 +When you send metrics like `foo:10|g` and `bar:20|g`, you'll see both private charts and your synthetic chart.
443
334 -- `name` defines the name of the app.
335 -- `metrics` is a Netdata [simple pattern](/src/libnetdata/simple_pattern/README.md). This pattern should match all the possible StatsD metrics that will be participating in the application `myapp`.
336 -- `private charts = yes|no`, enables or disables private charts for the metrics matched.
337 -- `gaps when not collected = yes|no`, enables or disables gaps on the charts of the application in case that no metrics are collected.
338 -- `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). We suggest not to use this (we have commented it out in the example) and let your app use the global default for Netdata, which is our dbengine.
444 +<details>
445 +<summary><strong>Synthetic Chart Example</strong></summary>
446 +<br/>
447
340 -- `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 documentation for the Agent's [Database](/src/database/README.md).
448 +Example of a synthetic chart combining multiple metrics:
449
342 -`[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.
450 +![Synthetic chart example](https://user-images.githubusercontent.com/2662304/28942317-958a2c68-78a3-11e7-853f-32850141dd36.png)
451 +</details>
452
344 -Then, add any number of charts. Each chart should start with `[id]`. The chart will be called `app_name.id`. `family` controls the submenu on the dashboard. `context` controls the alert templates. `priority` controls the ordering of the charts on the dashboard. The rest of the settings are informational.
453 +#### Application Section Options
454
346 -Add any number of metrics to a chart, using `dimension` lines. These lines accept 5 space separated parameters:
455 +The `[app]` section defines the application and has these options:
456
348 -1. the metric name, as it is collected (it has to be matched by the `metrics =` pattern of the app)
349 -2. the dimension name, as it should be shown on the chart
350 -3. an optional selector (type) of the value to shown (see below)
351 -4. an optional multiplier
352 -5. an optional divider
353 -6. optional flags, space separated and enclosed in quotes. All the external plugins `DIMENSION` flags can be used. Currently, the only usable flag is `hidden`, to add the dimension, but not show it on the dashboard. This is usually needed to have the values available for percentage calculation, or use them in alerts.
457 +:::note
458
355 -So, the format is this:
459 +- **name** - Defines the application name
460 +- **metrics** - [Simple pattern](https://github.com/netdata/netdata/blob/master/src/libnetdata/simple_pattern/README.md) matching all metrics for this app
461 +- **private charts** - Enable/disable private charts for matched metrics (yes|no)
462 +- **gaps when not collected** - Show gaps when no metrics are collected (yes|no)
463 +- **memory mode** - Sets memory mode for application charts (optional, default is global Netdata setting)
464 +- **history** - Size of round-robin database (optional, only relevant with `memory mode = save`)
465
357 -```
358 -dimension = [pattern] METRIC NAME TYPE MULTIPLIER DIVIDER OPTIONS
359 -```
466 +:::
467
361 -`pattern` is a keyword. When set, `METRIC` is expected to be a Netdata [simple pattern](/src/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.
468 +#### Dictionary Section
469
363 -`TYPE`, `MULTIPLIER`, `DIVIDER` and `OPTIONS` are optional.
470 +`[dictionary]` defines name-value pairs for renaming metrics in synthetic charts. This allows you to:
471
365 -`TYPE` can be:
472 +- Define dimension names globally for the whole app
473 +- Rename dimensions when using patterns
474 +- Create more human-readable names for technical metrics
475
367 -- `events` to show the number of events received by StatsD for this metric
368 -- `last` to show the last value, as calculated at the flush interval of the metric (the default)
476 +The dictionary can be empty or omitted if not needed.
477
370 -Then for histograms and timers the following types are also supported:
478 +#### Chart Definitions
479
372 -- `min`, show the minimum value
373 -- `max`, show the maximum value
374 -- `sum`, show the sum of all values
375 -- `average` (same as `last`)
376 -- `percentile`, show the 95th percentile (or any other percentile, as configured at StatsD global config)
377 -- `median`, show the median of all values (i.e. sort all values and get the middle value)
378 -- `stddev`, show the standard deviation of the values
480 +Each chart starts with `[id]` and will be named `app_name.id`. Key settings for charts:
481
380 -#### Example synthetic charts
482 +:::note
483
382 -StatsD metrics: `foo` and `bar`.
484 +- **family** - Controls dashboard submenu placement
485 +- **context** - Controls alert templates
486 +- **priority** - Controls chart ordering
487 +- **type** - Chart visualization type (line, area, stacked)
488 +- **units** - Chart measurement units
489
384 -Contents of file `/etc/netdata/statsd.d/foobar.conf`:
490 +:::
491
386 -```
387 -[app]
388 - name = foobarapp
389 - metrics = foo bar
390 - private charts = yes
391 -
392 -[foobar_chart1]
393 - title = Hey, foo and bar together
394 - family = foobar_family
395 - context = foobarapp.foobars
396 - units = foobars
397 - type = area
398 - dimension = foo 'foo me' last 1 1
399 - dimension = bar 'bar me' last 1 1
400 -```
401 -
402 -Metrics sent to statsd: `foo:10|g` and `bar:20|g`.
492 +#### [Dimension](https://learn.netdata.cloud/docs/developer-and-contributor-corner/glossary#d) Format
493
404 -Private charts:
494 +Add metrics to charts using `dimension` lines with this format:
495
406 -![screenshot from 2017-08-03 23-28-19](https://user-images.githubusercontent.com/2662304/28942295-7c3a73a8-78a3-11e7-88e5-a9a006bb7465.png)
496 +```
497 +dimension = [pattern] METRIC NAME TYPE MULTIPLIER DIVIDER OPTIONS
498 +```
499
408 -Synthetic chart:
500 +Where:
501
410 -![screenshot from 2017-08-03 23-29-14](https://user-images.githubusercontent.com/2662304/28942317-958a2c68-78a3-11e7-853f-32850141dd36.png)
502 +1. **METRIC** - The metric name as collected (must match the `metrics` pattern)
503 +2. **NAME** - The dimension name to display (can use dictionary for renaming)
504 +3. **TYPE** - (Optional) Value selector like `events`, `last`, `min`, `max`, etc.
505 +4. **MULTIPLIER** - (Optional) Value to multiply the metric by
506 +5. **DIVIDER** - (Optional) Value to divide the metric by
507 +6. **OPTIONS** - (Optional) Flags like `hidden` to include but not display a dimension
508
412 -#### Renaming StatsD synthetic charts' metrics
509 +<details>
510 +<summary><strong>Renaming StatsD Synthetic Charts' Metrics</strong></summary>
511 +<br/>
512
414 -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`
513 +You can define a dictionary to rename metrics sent by StatsD clients. This allows you to transmit the response code `200` while Netdata displays it as `successful connection`.
514
515 The `[dictionary]` section accepts any number of `name = value` pairs.
516
517 Netdata uses this dictionary as follows:
518
420 -1. When a `dimension` has a non-empty `NAME`, that name is looked up at the dictionary.
519 +1. When a `dimension` has a non-empty `NAME`, that name is looked up in the dictionary
520 +2. If the above lookup finds nothing, the original StatsD metric name is looked up
521 +3. If any lookup succeeds, Netdata uses the dictionary's `value` for the dimension name
522
422 -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.
523 +The dimensions will have the original StatsD metric name as ID and the dictionary value as name.
524
424 -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.
525 +You can use the dictionary in two ways:
526
426 -Use the dictionary in 2 ways:
527 +1. Set `dimension = myapp.metric1 ''` and have in the dictionary `myapp.metric1 = metric1 name`
528 +2. Set `dimension = myapp.metric1 'm1'` and have in the dictionary `m1 = metric1 name`
529
428 -1. set `dimension = myapp.metric1 ''` and have at the dictionary `myapp.metric1 = metric1 name`
429 -2. set `dimension = myapp.metric1 'm1'` and have at the dictionary `m1 = metric1 name`
530 +In both cases, the dimension will be added with ID `myapp.metric1` and named `metric1 name`. In alerts, you can reference it as either `${myapp.metric1}` or `${metric1 name}`.
531
431 -In both cases, the dimension will be added with ID `myapp.metric1` and will be named `metric1 name`. So, in alerts use either of the 2 as `${myapp.metric1}` or `${metric1 name}`.
532 +:::note
533
433 -> 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.
534 +If you add the same StatsD metric multiple times to a chart, Netdata will append `TYPE` to the dimension ID, so `myapp.metric1` will become `myapp.metric1_last` or `myapp.metric1_events`. If you add the same metric with the same `TYPE` multiple times, Netdata will also append an incremental counter, e.g., `myapp.metric1_last1`, `myapp.metric1_last2`, etc.
535
435 -#### Dimension patterns
536 +:::
537
437 -Netdata allows adding multiple dimensions to a chart, by matching the StatsD metrics with a Netdata simple pattern.
538 +</details>
539
439 -Assume we have an API that provides StatsD metrics for each response code per method it supports, like these:
540 +<details>
541 +<summary><strong>Dimension Patterns</strong></summary>
542 +<br/>
543 +
544 +Netdata allows adding multiple dimensions to a chart by matching StatsD metrics with a **pattern**.
545 +
546 +For example, if you have an API that provides StatsD metrics for each response code per method:
547
548 ```
549 myapp.api.get.200
@@ -453,7 +560,7 @@ myapp.api.all.400
560 myapp.api.all.500
561 ```
562
456 -In order to add all the response codes of `myapp.api.get` to a chart, we simply make the following configuration:
563 +To add all response codes of `myapp.api.get` to a chart:
564
565 ```
566 [api_get_responses]
@@ -461,9 +568,9 @@ In order to add all the response codes of `myapp.api.get` to a chart, we simply
568 dimension = pattern 'myapp.api.get.* '' last 1 1
569 ```
570
464 -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.
571 +This adds dimensions named `200`, `400`, and `500`. Netdata extracts the wildcard part of the metric name.
572
466 -You can rename the dimensions with this:
573 +You can rename these dimensions with the dictionary:
574
575 ```
576 [dictionary]
@@ -476,9 +583,11 @@ You can rename the dimensions with this:
583 dimension = pattern 'myapp.api.get.* 'get.' last 1 1
584 ```
585
479 -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`).
586 +The `NAME` prefix `get.` is combined with the wildcarded part to look up in the dictionary. So `500` becomes `get.500`, which is looked up to find `500 cannot connect to db`.
587
481 -To add all 200s across all API methods to a chart, you can do this:
588 +### More Pattern Examples
589 +
590 +To add all 200s across all API methods to a chart:
591
592 ```
593 [ok_by_method]
@@ -486,9 +595,9 @@ To add all 200s across all API methods to a chart, you can do this:
595 dimension = pattern 'myapp.api.*.200 '' last 1 1
596 ```
597
489 -The above will add `get`, `post`, `del` and `all` to the chart.
598 +This adds `get`, `post`, `del`, and `all` to the chart.
599
491 -If `all` is not wanted (a `stacked` chart does not need the `all` dimension, since the sum of the dimensions provides the total), the line should be:
600 +To exclude the `all` method:
601
602 ```
603 [ok_by_method]
@@ -496,9 +605,7 @@ If `all` is not wanted (a `stacked` chart does not need the `all` dimension, sin
605 dimension = pattern '!myapp.api.all.* myapp.api.*.200 '' last 1 1
606 ```
607
499 -With the above, all methods except `all` will be added to the chart.
500 -
501 -To automatically rename the methods, you can use this:
608 +To rename methods automatically:
609
610 ```
611 [dictionary]
@@ -511,150 +618,130 @@ To automatically rename the methods, you can use this:
618 dimension = pattern '!myapp.api.all.* myapp.api.*.200 'method.' last 1 1
619 ```
620
514 -Using the above, the dimensions will be added as `GET`, `ADD` and `DELETE`.
621 +This adds dimensions named `GET`, `ADD`, and `DELETE`.
622 +</details>
623
516 -## StatsD examples
624 +## Using StatsD with Different Languages
625
518 -### Python
626 +<details>
627 +<summary><strong>Python</strong></summary>
628 +<br/>
629
520 -It's really easy to instrument your python application with StatsD, for example using [jsocol/pystatsd](https://github.com/jsocol/pystatsd).
630 +Using [jsocol/pystatsd](https://github.com/jsocol/pystatsd):
631
632 ```python
633 import statsd
634 +
635 c = statsd.StatsClient('localhost', 8125)
525 -c.incr('foo') # Increment the 'foo' counter.
636 +c.incr('foo') # Increment the 'foo' counter.
637 for i in range(100000000):
527 - c.incr('bar')
528 - c.incr('foo')
529 - if i % 3:
530 - c.decr('bar')
531 - c.timing('stats.timed', 320) # Record a 320ms 'stats.timed'.
638 + c.incr('bar')
639 + c.incr('foo')
640 + if i % 3:
641 + c.decr('bar')
642 + c.timing('stats.timed', 320) # Record a 320ms 'stats.timed'.
643 ```
644
534 -You can find detailed documentation in their [documentation page](https://statsd.readthedocs.io/en/v3.3/).
645 +See the [full documentation](https://statsd.readthedocs.io/en/v3.3/) for more details.
646 +</details>
647
536 -### Javascript and Node.js
648 +<details>
649 +<summary><strong>JavaScript and Node.js</strong></summary>
650 +<br/>
651
538 -Using the client library by [sivy/node-statsd](https://github.com/sivy/node-statsd), you can easily embed StatsD into your Node.js project.
652 +Using [sivy/node-statsd](https://github.com/sivy/node-statsd):
653
654 ```javascript
655 var StatsD = require('node-statsd'),
542 - client = new StatsD();
656 + client = new StatsD();
657
544 - // Timing: sends a timing command with the specified milliseconds
545 - client.timing('response_time', 42);
658 +// Timing: sends a timing command with the specified milliseconds
659 +client.timing('response_time', 42);
660
547 - // Increment: Increments a stat by a value (default is 1)
548 - client.increment('my_counter');
661 +// Increment: Increments a stat by a value (default is 1)
662 +client.increment('my_counter');
663
550 - // Decrement: Decrements a stat by a value (default is -1)
551 - client.decrement('my_counter');
664 +// Decrement: Decrements a stat by a value (default is -1)
665 +client.decrement('my_counter');
666
553 - // Using the callback
554 - client.set(['foo', 'bar'], 42, function(error, bytes){
667 +// Using the callback
668 +client.set(['foo', 'bar'], 42, function (error, bytes) {
669 //this only gets called once after all messages have been sent
556 - if(error){
557 - console.error('Oh noes! There was an error:', error);
670 + if (error) {
671 + console.error('Oh noes! There was an error:', error);
672 } else {
559 - console.log('Successfully sent', bytes, 'bytes');
673 + console.log('Successfully sent', bytes, 'bytes');
674 }
561 - });
562 -
563 - // Sampling, tags and callback are optional and could be used in any combination
564 - client.histogram('my_histogram', 42, 0.25); // 25% Sample Rate
565 - client.histogram('my_histogram', 42, ['tag']); // User-defined tag
566 - client.histogram('my_histogram', 42, next); // Callback
567 - client.histogram('my_histogram', 42, 0.25, ['tag']);
568 - client.histogram('my_histogram', 42, 0.25, next);
569 - client.histogram('my_histogram', 42, ['tag'], next);
570 - client.histogram('my_histogram', 42, 0.25, ['tag'], next);
571 -```
572 -### Other languages
573 -
574 -You can also use StatsD with:
575 -- Golang, thanks to [alexcesaro/statsd](https://github.com/alexcesaro/statsd)
576 -- Ruby, thanks to [reinh/statsd](https://github.com/reinh/statsd)
577 -- Java, thanks to [DataDog/java-dogstatsd-client](https://github.com/DataDog/java-dogstatsd-client)
578 -
675 +});
676
580 -### Shell
581 -
582 -Getting the proper support for a programming language is not always easy, but the Unix shell is available on most Unix systems. You can use shell and `nc` to instrument your systems and send metric data to Netdata's StatsD implementation.
583 -
584 -Using the method you can send metrics from any script. You can generate events like: backup.started, backup.ended, backup.time, or even tail logs and convert them to metrics.
585 -
586 -> **IMPORTANT**:
587 ->
588 -> To send StatsD messages you need from the `netcat` package, the `nc` command.
589 -> There are multiple versions of this package. Please try to experiment with the `nc` command you have available on your right system, to find the right parameters.
590 ->
591 -> In the examples below, we assume the `openbsd-netcat` is installed.
677 +// Sampling, tags and callback are optional and could be used in any combination
678 +client.histogram('my_histogram', 42, 0.25); // 25% Sample Rate
679 +client.histogram('my_histogram', 42, ['tag']); // User-defined tag
680 +client.histogram('my_histogram', 42, next); // Callback
681 +client.histogram('my_histogram', 42, 0.25, ['tag']);
682 +client.histogram('my_histogram', 42, 0.25, next);
683 +client.histogram('my_histogram', 42, ['tag'], next);
684 +client.histogram('my_histogram', 42, 0.25, ['tag'], next);
685 +```
686
593 -If you plan to send short StatsD events at sporadic occasions, use UDP. The messages should not be too long (remember, most networks support up to 1500 bytes MTU, which is also the limit for StatsD messages over UDP). The good thing is that using UDP will not block your script, even if the StatsD server is not there (UDP messages are "fire-and-forget").
687 +</details>
688
689 +<details>
690 +<summary><strong>Other Languages</strong></summary>
691 +<br/>
692
596 -For UDP use this:
693 +StatsD clients are available for many languages:
694
598 -```sh
599 -echo "APPLICATION.METRIC:VALUE|TYPE" | nc -u -w 0 localhost 8125
600 -```
695 +- Golang: [alexcesaro/statsd](https://github.com/alexcesaro/statsd)
696 +- Ruby: [reinh/statsd](https://github.com/reinh/statsd)
697 +- Java: [DataDog/java-dogstatsd-client](https://github.com/DataDog/java-dogstatsd-client)
698
602 -`-u` turns on UDP, `-w 0` tells `nc` not to wait for a response from StatsD (idle time to close the connection).
699 +</details>
700
604 -where:
701 +<details>
702 +<summary><strong>Shell Script</strong></summary>
703 +<br/>
704
606 -- `APPLICATION` is any name for your application
607 -- `METRIC` is the name for the specific metric
608 -- `VALUE` is the value for that metric (**meters**, **counters**, **gauges**, **timers** and **histograms** accept integer/decimal/fractional numbers, **sets** and **dictionaries** accept strings)
609 -- `TYPE` is one of `m`, `c`, `g`, `ms`, `h`, `s`, `d` to define the metric type.
705 +You can use the Unix shell with `nc` to send StatsD metrics from any script.
706
611 -For tailing a log and converting it to metrics, do something like this:
707 +:::important
708
613 -```sh
614 -tail -f some.log | awk 'awk commands to parse the log and format statsd metrics' | nc -N -w 120 localhost 8125
615 -```
709 +You'll need the `netcat` package with the `nc` command. Different versions have different parameters, so experiment to find what works on your system. The examples below assume `openbsd-netcat` is installed.
710
617 -`-N` tells `nc` to close the socket once it receives EOF on its input. `-w 120` tells `nc` to stop if the connection is idle for 120 seconds. The timeout is needed to stop the `nc` command if you restart Netdata while `nc` is connected to it. Without it, `nc` will sit idle forever.
711 +:::
712
619 -When you embed the above commands to a script, you may notice that all the metrics are sent to StatsD with a delay. They are buffered in the pipes `|`. You can turn them to real-time by prepending each command with `stdbuf -i0 -oL -eL command to be run`, like this:
713 +#### Using UDP (for sporadic events)
714
715 ```sh
622 -stdbuf -i0 -oL -eL tail -f some.log |\
623 - stdbuf -i0 -oL -eL awk 'awk commands to parse the log and format statsd metrics' |\
624 - stdbuf -i0 -oL -eL nc -N -w 120 localhost 8125
716 +echo "APPLICATION.METRIC:VALUE|TYPE" | nc -u -w 0 localhost 8125
717 ```
718
627 -If you use `mawk` you also need to run awk with `-W interactive`.
719 +- `-u` enables UDP
720 +- `-w 0` tells `nc` not to wait for a response
721
722 Examples:
723
631 -To set `myapp.used_memory` as gauge to value `123456`, use:
632 -
724 ```sh
725 +# Set a gauge value
726 echo "myapp.used_memory:123456|g|#units:bytes" | nc -u -w 0 localhost 8125
635 -```
727
637 -To increment `myapp.files_sent` by `10`, as a counter, use:
728 +# Increment a counter
729 +echo "myapp.files_sent:10|c|#units:files" | nc -u -w 0 localhost 8125
730
639 -```sh
640 -echo "myapp.files_sent:10|c|#units:files" | nc -u -w 0 localhost 8125
731 +# Send multiple metrics
732 +printf "myapp.used_memory:123456|g|#units:bytes\nmyapp.files_sent:10|c|#units:files\n" | nc -u -w 0 localhost 8125
733 ```
734
643 -You can send multiple metrics like this:
644 -
645 -```sh
646 -# send multiple metrics via UDP
647 -printf "myapp.used_memory:123456|g|#units:bytes\nmyapp.files_sent:10|c|#units:files\n" | nc -u -w 0 localhost 8125
648 -```
649 -
650 -Remember, for UDP communication each packet should not exceed the MTU. So, if you plan to push too many metrics at once, prefer TCP communication:
735 +#### Using TCP (for many metrics at once)
736
737 ```sh
738 # send multiple metrics via TCP
739 cat /tmp/statsd.metrics.txt | nc -N -w 120 localhost 8125
740 ```
741
657 -You can also use this little function to take care of all the details:
742 +#### Helper Function for Shell Scripts
743 +
744 +This function handles both UDP and TCP automatically:
745
746 ```sh
747 #!/usr/bin/env bash
@@ -684,216 +771,137 @@ then
771 fi
772 ```
773
687 -You can use it like this:
774 +Usage:
775
776 ```sh
690 -# first, source it in your script
777 +# source it in your script
778 source statsd.sh
779
693 -# then, at any point:
780 +# then use it anywhere
781 statsd "myapp.used_memory:123456|g|#units:bytes" "myapp.files_sent:10|c|#units:files" ...
695 -```
782
697 -or even at a terminal prompt, like this:
698 -
699 -```sh
783 +# or at command line
784 ./statsd.sh "myapp.used_memory:123456|g|#units:bytes" "myapp.files_sent:10|c|#units:files" ...
785 ```
786
703 -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.
787 +The function automatically switches to TCP if the metrics exceed 1000 bytes.
788 +</details>
789
705 -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.
790 +## Step-by-Step Guide: Monitoring K6 with StatsD
791
707 -## StatsD Step By Step Guide
792 +This guide demonstrates how to use Netdata's StatsD to visualize metrics from [k6](https://k6.io), an open-source load testing tool.
793
709 -In this guide, we'll go through a scenario of visualizing our data in Netdata in a matter of seconds using
710 -[k6](https://k6.io), an open-source tool for automating load testing that outputs metrics to the StatsD format.
794 +<details>
795 +<summary><strong>Prerequisites</strong></summary>
796 +<br/>
797
712 -Although we'll use k6 as the use-case, the same principles can be applied to every application that supports
713 -the StatsD protocol. Simply enable the StatsD output and point it to the node that runs Netdata, which is `localhost` in this case.
798 +- A node with [Netdata](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md) installed
799 +- [k6](https://k6.io/docs/getting-started/installation) installed
800
715 -In general, the process for creating a StatsD collector can be summarized in 2 steps:
801 +</details>
802
717 -- Run an experiment by sending StatsD metrics to Netdata, without any prior configuration. This will create
718 - a chart per metric (called private charts) and will help you verify that everything works as expected from the application side of things.
803 +<details>
804 +<summary><strong>The Process in Brief</strong></summary>
805 +<br/>
806
720 - - Make sure to reload the dashboard tab **after** you start sending data to Netdata.
807 +1. **Run an experiment** sending StatsD metrics to Netdata without configuration
808 + - This creates a private chart per metric
809 + - Reload the dashboard after starting to send data
810
722 -- Create a configuration file for your app using [edit-config](/docs/netdata-agent/configuration/README.md): `sudo ./edit-config
723 - statsd.d/myapp.conf`
811 +2. **Create a configuration file** for your app:
812 + ```
813 + sudo ./edit-config statsd.d/myapp.conf
814 + ```
815 + - This organizes metrics into meaningful sections
816
725 - - Each app will have it's own section in the right-hand menu.
817 +</details>
818
727 -Now, let's see the above process in detail.
819 +<details>
820 +<summary><strong>Understanding Your Metrics</strong></summary>
821 +<br/>
822
729 -### Prerequisites
823 +First, understand what metrics your application provides. For k6, check their [metrics documentation](https://k6.io/docs/using-k6/metrics/).
824
731 -- A node with the [Netdata](/packaging/installer/README.md) installed.
732 -- An application to instrument. For this guide, that will be [k6](https://k6.io/docs/getting-started/installation).
825 +When instrumenting your own code, you'll need to decide:
826
734 -### Understanding the metrics
827 +- What to measure
828 +- Which StatsD metric type is appropriate for each measurement
829
736 -The real in instrumenting an application with StatsD for you is to decide what metrics you
737 -want to visualize and how you want them grouped. In other words, you need decide which metrics
738 -will be grouped in the same charts and how the charts will be grouped on Netdata's dashboard.
830 +</details>
831
740 -Start with documentation for the particular application that you want to monitor (or the
741 -technological stack that you are using). In our case, the
742 -[k6 documentation](https://k6.io/docs/using-k6/metrics/) has a whole page dedicated to the
743 -metrics output by k6, along with descriptions.
832 +<details>
833 +<summary><strong>Exploring Available Metrics with Private Charts</strong></summary>
834 +<br/>
835
745 -If you are using StatsD to monitor an existing application, you don't have much control over
746 -these metrics. For example, k6 has a type called `trend`, which is identical to timers and histograms.
747 -Thus, _k6 is clearly dictating_ which metrics can be used as histograms and simple gauges.
836 +Every StatsD metric initially gets its own "private chart." While you'll likely disable this in production, it's helpful during setup to see all available metrics.
837
749 -On the other hand, if you are instrumenting your own code, you will need to not only decide what are
750 -the "things" that you want to measure, but also decide which StatsD metric type is the appropriate for each.
838 +Private charts clearly show the metric type (gauge, timer, etc.) and available operations for complex types like histograms.
839 +</details>
840
752 -### Use private charts to see all available metrics
841 +<details>
842 +<summary><strong>Creating a StatsD Configuration File</strong></summary>
843 +<br/>
844
754 -In Netdata, every metric will receive its own chart, called a `private chart`. Although in the
755 -final implementation this is something that we will disable, since it can create considerable noise
756 -(imagine having 100s of metrics), it’s very handy while building the configuration file.
845 +Use Netdata's [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) to create a new file:
846
758 -You can get a quick visual representation of the metrics and their type (e.g it’s a gauge, a timer, etc.).
847 +```bash
848 +sudo ./edit-config statsd.d/k6.conf
849 +```
850
760 -An important thing to notice is that StatsD has different types of metrics, as illustrated in the
761 -[supported metrics](#metrics-supported-by-netdata). Histograms and timers support mathematical operations
762 -to be performed on top of the baseline metric, like reporting the `average` of the value.
851 +Start with this basic configuration:
852
764 -Here are some examples of default private charts. You can see that the histogram private charts will
765 -visualize all the available operations.
853 +```
854 +[app]
855 + name = k6
856 + metrics = k6*
857 + private charts = yes
858 + gaps when not collected = no
859 + memory mode = dbengine
860 +```
861
767 -**Gauge private chart**
862 +</details>
863
769 -![Gauge metric example](https://i.imgur.com/Sr5nJEV.png)
864 +<details>
865 +<summary><strong>Organizing Metrics</strong></summary>
866 +<br/>
867
771 -**Histogram private chart**
868 +Next, decide how to organize metrics in the Netdata dashboard:
869
773 -![Timer metric example](https://i.imgur.com/P4p0hvq.png)
870 +1. **Dictionary** - Create human-readable names for technical metrics
871 + ```
872 + [dictionary]
873 + http_req_blocked = Blocked HTTP Requests
874 + http_req_connecting = Connecting HTTP Requests
875 + http_req_receiving = Receiving HTTP Requests
876 + http_reqs = Total HTTP requests
877 + ```
878
775 -### Create a new StatsD configuration file
879 +2. **Families** - Group charts into dashboard submenus. For k6, we'll use `k6 native metrics` and `http metrics` families.
880
777 -Start by creating a new configuration file under the `statsd.d/` folder in the
778 -[Netdata config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory).
779 -Use [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config)
780 -to create a new file called `k6.conf`.
881 +3. **[Dimensions](https://learn.netdata.cloud/docs/developer-and-contributor-corner/glossary#d)** - Choose which metrics to show and how to group them in charts
882
782 -```bash=
783 -sudo ./edit-config statsd.d/k6.conf
784 -```
883 +</details>
884 +
885 +<details>
886 +<summary><strong>Complete Configuration Example</strong></summary>
887 +<br/>
888
786 -Copy the following configuration into your file as a starting point.
889 +Here's a complete configuration for k6:
890
788 -```text
891 +```
892 [app]
893 name = k6
894 metrics = k6*
895 private charts = yes
896 gaps when not collected = no
897 memory mode = dbengine
795 -```
898
797 -Next, you need is to understand how to organize metrics in Netdata’s StatsD.
798 -
799 -#### Synthetic charts
800 -
801 -Netdata lets you group the metrics exposed by your instrumented application with _synthetic charts_.
802 -
803 -First, create a `[dictionary]` section to transform the names of the metrics into human-readable equivalents.
804 -`http_req_blocked`, `http_req_connecting`, `http_req_receiving`, and `http_reqs` are all metrics exposed by k6.
805 -
806 -```
899 [dictionary]
900 http_req_blocked = Blocked HTTP Requests
901 http_req_connecting = Connecting HTTP Requests
902 http_req_receiving = Receiving HTTP Requests
903 http_reqs = Total HTTP requests
812 -```
813 -
814 -Continue this dictionary process with any other metrics you want to collect with Netdata.
815 -
816 -#### Families and context
817 -
818 -Families and context are additional ways to group metrics. Families control the submenu at right-hand menu and
819 -it's a subcategory of the section. Given the metrics given by K6, we are organizing them in 2 major groups,
820 -or `families`: `k6 native metrics` and `http metrics`.
821 -
822 -Context is a second way to group metrics, when the metrics are of the same nature but different origin. In
823 -our case, if we ran several different load testing experiments side-by-side, we could define the same app,
824 -but different context (e.g `http_requests.experiment1`, `http_requests.experiment2`).
825 -
826 -Find more details about family and context in our [documentation](/src/web/README.md#families).
827 -
828 -#### Dimensions
829 -
830 -Now, having decided on how we are going to group the charts, we need to define how we are going to group
831 -metrics into different charts. This is particularly important, since we decide:
832 -
833 -- What metrics **not** to show, since they are not useful for our use-case.
834 -- What metrics to consolidate into the same charts, so as to reduce noise and increase visual correlation.
835 -
836 -The dimension option has this syntax: `dimension = [pattern] METRIC NAME TYPE MULTIPLIER DIVIDER OPTIONS`
837 -
838 -- **pattern**: A keyword that tells the StatsD server the `METRIC` string is actually a
839 - [simple pattern](/src/libnetdata/simple_pattern/README.md).
840 - We don't use simple patterns in the example, but if we wanted to visualize all the `http_req` metrics, we
841 - could have a single dimension: `dimension = pattern 'k6.http_req*' last 1 1`. Find detailed examples with
842 - patterns in [dimension patterns](/src/collectors/statsd.plugin/README.md#dimension-patterns).
843 -
844 -- **METRIC** The id of the metric as it comes from the client. You can easily find this in the private charts above,
845 - for example: `k6.http_req_connecting`.
904
847 -- **NAME**: The name of the dimension. You can use the dictionary to expand this to something more human-readable.
848 -
849 -- **TYPE**:
850 -
851 - - For all charts:
852 - - `events`: The number of events (data points) received by the StatsD server
853 - - `last`: The last value that the server received
854 -
855 - - For histograms and timers:
856 - - `min`, `max`, `sum`, `average`, `percentile`, `median`, `stddev`: This is helpful if you want to see
857 - different representations of the same value. You can find an example at the `[iteration_duration]`
858 - above. Note that the baseline `metric` is the same, but the `name` of the dimension is different,
859 - since we use the baseline, but we perform a computation on it, creating a different final metric for
860 - visualization(dimension).
861 -
862 -- **MULTIPLIER DIVIDER**: Handy if you want to convert Kilobytes to Megabytes or you want to give negative value.
863 - The second is handy for better visualization of send/receive. You can find an example at the **packets** submenu of the **IPv4 Networking Section**.
864 -
865 -If you define a chart, run Netdata to visualize metrics, and then add or remove a dimension from that chart,
866 -this will result in a new chart with the same name, confusing Netdata. If you change the dimensions of the chart,
867 -make sure to also change the `name` of that chart, since it serves as the `id` of that chart in Netdata's storage.
868 -(e.g http_req --> http_req_1).
869 -
870 -#### Finalize your StatsD configuration file
871 -
872 -It's time to assemble all the pieces together and create the synthetic charts that will consist our application
873 -dashboard in Netdata. We can do it in a few simple steps:
874 -
875 -- Decide which metrics we want to use (we have viewed all of them as private charts). For example, we want to use
876 - `k6.http_requests`, `k6.vus`, etc.
877 -
878 -- Decide how we want organize them in different synthetic charts. For example, we want `k6.http_requests`, `k6.vus`
879 - on their own, but `k6.http_req_blocked` and `k6.http_req_connecting` on the same chart.
880 -
881 -- For each synthetic chart, we define a **unique** name and a human readable title.
882 -
883 -- We decide at which `family` (submenu section) we want each synthetic chart to belong to. For example, here we
884 - have defined 2 families: `http requests`, `k6_metrics`.
885 -
886 -- If we have multiple instances of the same metric, we can define different contexts, (Optional).
887 -
888 -- We define a dimension according to the syntax we highlighted above.
889 -
890 -- We define a type for each synthetic chart (line, area, stacked)
891 -
892 -- We define the units for each synthetic chart.
893 -
894 -Following the above steps, we append to the `k6.conf` that we defined above, the following configuration:
895 -
896 -```
905 [http_req_total]
906 name = http_req_total
907 title = Total HTTP Requests
@@ -960,82 +968,51 @@ Following the above steps, we append to the `k6.conf` that we defined above, the
968 type = stacked
969 ```
970
963 -Note that Netdata will report the rate for metrics and counters, even if k6 or another application
964 -sends an _absolute_ number. For example, k6 sends absolute HTTP requests with `http_reqs`,
965 -but Netdata visualizes that in `requests/second`.
971 +:::note
972 +
973 +Netdata will report the rate for metrics and counters even if your application sends absolute numbers. For example, k6 sends absolute HTTP requests with `http_reqs`, but Netdata visualizes that as `requests/second`.
974 +
975 +:::
976
967 -To enable this StatsD configuration, [restart Netdata](/docs/netdata-agent/start-stop-restart.md).
977 +Restart Netdata to enable this configuration.
978 +</details>
979
969 -### Final touches
980 +<details>
981 +<summary><strong>Adding Custom Icons and Descriptions</strong></summary>
982 +<br/>
983
971 -At this point, you have used StatsD to gather metrics for k6, creating a whole new section in your
972 -Netdata dashboard in the process. Moreover, you can further customize the icon of the particular section,
973 -as well as the description for each chart.
984 +You can customize the section icon and add helpful chart descriptions.
985
975 -While the following configuration will be placed in a new file, as the documentation suggests, it is
976 -instructing to use `dashboard_info.js` as a template. Open the file and see how the rest of sections and collectors have been defined.
986 +Create a custom dashboard info file:
987
978 -```javascript=
988 +```javascript
989 netdataDashboard.menu = {
990 'k6': {
991 title: 'K6 Load Testing',
992 icon: '<i class="fas fa-cogs"></i>',
993 info: 'k6 is an open-source load testing tool and cloud service providing the best developer experience for API performance testing.'
994 },
985 - .
986 - .
987 - .
988 -```
995 +};
996
990 -We can then add a description for each chart. Simply find the following section in `dashboard_info.js` to understand how a chart definitions are used:
991 -
992 -```javascript=
993 -netdataDashboard.context = {
994 - 'system.cpu': {
995 - info: function (os) {
996 - void (os);
997 - return 'Total CPU utilization (all cores). 100% here means there is no CPU idle time at all. You can get per core usage at the <a href="#menu_cpu">CPUs</a> section and per application usage at the <a href="#menu_apps">Applications Monitoring</a> section.'
998 - + netdataDashboard.sparkline('<br/>Keep an eye on <b>iowait</b> ', 'system.cpu', 'iowait', '%', '. If it is constantly high, your disks are a bottleneck and they slow your system down.')
999 - + netdataDashboard.sparkline('<br/>An important metric worth monitoring, is <b>softirq</b> ', 'system.cpu', 'softirq', '%', '. A constantly high percentage of softirq may indicate network driver issues.');
1000 - },
1001 - valueRange: "[0, 100]"
1002 - },
1003 -```
1004 -
1005 -Afterwards, you can open your `custom_dashboard_info.js`, as suggested in the documentation linked above,
1006 -and add something like the following example:
1007 -
1008 -```javascript=
997 netdataDashboard.context = {
998 'k6.http_req_duration': {
1011 - info: "Total time for the request. It's equal to http_req_sending + http_req_waiting + http_req_receiving (i.e. how long did the remote server take to process the request and respond, without the initial DNS lookup/connection times)"
1012 - },
1013 -
999 + info: "Total time for the request. It's equal to http_req_sending + http_req_waiting + http_req_receiving (i.e. how long did the remote server take to process the request and respond, without the initial DNS lookup/connection times)"
1000 + },
1001 +};
1002 ```
1015 -The chart is identified as ``<section_name>.<chart_name>``.
1003
1017 -These descriptions can greatly help the Netdata user who is monitoring your application in the midst of an incident.
1004 +These descriptions help users monitor your application, especially during incidents. The `info` field supports HTML, allowing you to embed links and instructions.
1005 +</details>
1006
1019 -The `info` field supports `html`, embedding useful links and instructions in the description.
1007 +<details>
1008 +<summary><strong>Contributing Your Collector</strong></summary>
1009 +<br/>
1010
1021 -### Vendoring a new collector
1022 -
1023 -While we learned how to visualize any data source in Netdata using the StatsD protocol, we have also created a new collector.
1024 -
1025 -As long as you use the same underlying collector, every new `myapp.conf` file will create a new data
1026 -source and dashboard section for Netdata. Netdata loads all the configuration files by default, but it will
1027 -**not** create dashboard sections or charts, unless it starts receiving data for that particular data source.
1028 -This means that we can now share our collector with the rest of the Netdata community.
1029 -
1030 -- Make sure you follow the [contributing guide](https://github.com/netdata/.github/edit/main/CONTRIBUTING.md)
1031 -- Fork the netdata/netdata repository
1032 -- Place the configuration file inside `netdata/collectors/statsd.plugin`
1033 -- Add a reference in `netdata/collectors/statsd.plugin/Makefile.am`. For example, if we contribute the `k6.conf` file:
1034 -```Makefile
1035 -dist_statsdconfig_DATA = \
1036 - example.conf \
1037 - k6.conf \
1038 - $(NULL)
1039 -```
1011 +Once you've created a working configuration, consider sharing it with the Netdata community:
1012
1013 +1. Follow the [contributing guide](https://github.com/netdata/.github/blob/main/CONTRIBUTING.md)
1014 +2. Fork the netdata/netdata repository
1015 +3. Place your configuration file in `netdata/collectors/statsd.plugin`
1016 +4. Add a reference in `netdata/collectors/statsd.plugin/Makefile.am`
1017
1018 +</details>