docs: task class: improve_docs — add private chart naming convention (#22577)
* docs: update docs/statsd-metric-query-chart-name * docs: Execution completed * docs: Execution completed * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com> Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
nedi-app[bot] committed
May 29, 2026 at 17:58 UTC
1e77413da6f3207e420d8f05aa13b5467d20982a
1 file changed
+40
src/collectors/statsd.plugin/README.md
+40
@@ -344,6 +344,46 @@ Netdata can visualize StatsD collected metrics in two ways:
344
345
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.
346
347
+#### Private Chart Naming Convention
348
+
349
+When querying StatsD metrics via the Netdata API, you must use the chart identifier that Netdata constructs from the metric name — not the raw metric name you sent to StatsD. The chart identifier is built as follows:
350
+
351
+- **Chart type** = `statsd_<first_word>` — where `<first_word>` is the portion of the metric name before the first `.` or `_`.
352
+- **Chart id** = `<remaining>_<metric_type>` — where `<remaining>` is the portion after the first `.` or `_`, and `<metric_type>` is one of: `gauge`, `counter`, `meter`, `timer`, `histogram`, `set`, or `dictionary`. If the metric name has no `.` or `_`, the chart id is just the `<metric_type>`.
353
+- **Full chart reference** = `<chart_type>.<chart_id>` — use this as the `chart` parameter in API queries.
354
+
355
+| Metric sent | Metric type | Chart type | Chart ID | Full chart reference |
356
+|------------------------------|-------------|-----------------|---------------------|-------------------------------------|
357
+| `test.metric:100\|c` | counter | `statsd_test` | `metric_counter` | `statsd_test.metric_counter` |
358
+| `myapp.used_memory:12345\|g` | gauge | `statsd_myapp` | `used_memory_gauge` | `statsd_myapp.used_memory_gauge` |
359
+| `myapp.requests:50\|ms` | timer | `statsd_myapp` | `requests_timer` | `statsd_myapp.requests_timer` |
360
+
361
+:::tip
362
+
363
+To discover the exact chart names available on your agent, run:
364
+
365
+```bash
366
+curl http://localhost:19999/api/v1/charts
367
+```
368
+
369
+Filter the results for IDs starting with `statsd_`. Use the returned chart `id` field (in `type.id` format) as the `chart` parameter in data queries.
370
+
371
+:::
372
+
373
+:::info
374
+
375
+**Troubleshooting "No metrics where matched to query":** This error typically occurs when you use the raw StatsD metric name (e.g., `statsd.test.metric`) as the `chart` parameter instead of the constructed chart reference (e.g., `statsd_test.metric_counter`). To resolve this, verify the correct chart name using `/api/v1/charts` before querying metric data.
376
+
377
+For example, after sending `test.metric:100|c` via StatsD, the correct query is:
378
+
379
+```bash
380
+curl "http://localhost:19999/api/v1/data?chart=statsd_test.metric_counter&after=-10&before=now"
381
+```
382
+
383
+The chart name `statsd_test.metric_counter` follows the `type.id` convention: type `statsd_test` (prefix + first dot-delimited word) and id `metric_counter` (remaining words + metric type).
384
+
385
+:::
386
+
387
Example: To create charts for all `myapp.*` metrics except `myapp.*.badmetric`:
388
389
```