docs: add snmp profile format to snmp collector doc (#21210)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Ilya Mashchenko committed
Oct 26, 2025 at 20:48 UTC
ca4bfb4c345df318c2e1bf12187002eb175d18e1
3 files changed
+51
-1
docs/.map/map.csv
+1
@@ -123,6 +123,7 @@ https://github.com/netdata/netdata/edit/master/docs/collecting-metrics/system-me
123
https://github.com/netdata/netdata/edit/master/docs/collecting-metrics/application-metrics.md,Application metrics,Unpublished,Collecting Metrics,"Monitor and troubleshoot every application on your infrastructure with per-second metrics, zero configuration, and meaningful charts."
124
https://github.com/netdata/netdata/edit/master/docs/collecting-metrics/container-metrics.md,Container metrics,Unpublished,Collecting Metrics,Use Netdata to collect per-second utilization and application-level metrics from Linux/Docker containers and Kubernetes clusters.
125
https://github.com/netdata/netdata/edit/master/src/collectors/COLLECTORS.md,Monitor Anything,Published,Collecting Metrics,Netdata gathers real-time metrics from hundreds of data sources using collectors. Most require zero configuration and are pre-configured out of the box.
126
+https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/snmp/profile-format.md,SNMP Profile Format,Published,Collecting Metrics,Learn how Netdata’s SNMP collector uses profiles.
127
collectors_integrations,,,,
128
,,,,
129
,,,,
src/go/plugin/go.d/collector/snmp/metadata.yaml
+22
-1
@@ -23,6 +23,21 @@ modules:
23
metrics_description: |
24
This SNMP collector discovers and monitors SNMP-enabled devices using **profiles**.
25
26
+ :::tip
27
+
28
+ See: [SNMP Profile Format](/src/go/plugin/go.d/collector/snmp/profile-format.md) to learn how to write profiles and define their fields.
29
+
30
+ **Profile locations**
31
+
32
+ | Type | Default path | Notes |
33
+ |------|---------------|--------|
34
+ | **Stock profiles** | `/usr/lib/netdata/conf.d/go.d/snmp.profiles/default/` | Provided with Netdata. |
35
+ | **User profiles** | `/etc/netdata/go.d/snmp.profiles/` | Place your custom or modified profiles here. |
36
+
37
+ Depending on your installation method, both paths may include the `/opt/netdata` prefix.
38
+
39
+ :::
40
+
41
A *profile* declares:
42
- device selectors (e.g. `sysObjectID`, `sysDescr`) for auto-matching,
43
- which OIDs to collect (scalars and tables),
@@ -55,7 +70,7 @@ modules:
70
- Supports single IPs, ranges, and CIDR blocks (up to 512 IPs per subnet).
71
- Uses the provided SNMP credentials (v1/v2c/v3) to probe devices.
72
- Caches discovery results (configurable) to reduce network load.
58
- - At collection time, each discovered device is matched to the appropriate profile based on its `sysObjectID`, `sysDescr`, and the profile’s selector rules.
73
+ - At collection time, each discovered device is matched to the appropriate [profile](/src/go/plugin/go.d/collector/snmp/profile-format.md) based on its `sysObjectID`, `sysDescr`, and the profile’s selector rules.
74
75
The configuration file name is [go.d/sd/snmp.conf](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/config/go.d/sd/snmp.conf).
76
@@ -319,6 +334,12 @@ modules:
334
description: |
335
Metrics and charts are **defined by the matched SNMP profile(s)** at runtime. They differ by vendor/model/OS and may include, for example, interface counters, optics, CPU/memory, temperature, VLANs, and more. Use the **Metrics** tab on the device’s dashboard to see exactly what is collected for that device.
336
337
+ :::tip
338
+
339
+ To understand the structure of these profiles (metrics, tags, virtual metrics, etc.), see **[SNMP Profile Format](/src/go/plugin/go.d/collector/snmp/profile-format.md)**.
340
+
341
+ :::
342
+
343
If `ping.enabled` is true, ICMP latency/packet-loss charts are also provided (or exclusively, when `ping_only: true`).
344
availability: []
345
scopes: []
src/go/plugin/go.d/collector/snmp/profile-format.md
+28
@@ -604,6 +604,34 @@ metrics:
604
- Forces `ifInOctets` to be treated as a **gauge** (instantaneous value) instead of a rate.
605
- Normally, `Counter` types are automatically converted to per-second rates.
606
607
+### Chart Metadata
608
+
609
+Each metric or virtual metric can include an optional `chart_meta` block that defines how it appears in Netdata charts.
610
+
611
+This metadata **does not affect data collection** — it only controls how the chart is **named** and **grouped** in the Netdata dashboard.
612
+
613
+```yaml
614
+metrics:
615
+ - MIB: IF-MIB
616
+ table:
617
+ OID: 1.3.6.1.2.1.2.2
618
+ name: ifTable
619
+ symbols:
620
+ - OID: 1.3.6.1.2.1.2.2.1.10
621
+ name: ifInOctets
622
+ chart_meta:
623
+ description: Inbound network traffic
624
+ family: 'Network/Interface/Traffic/In'
625
+ unit: "bit/s"
626
+```
627
+
628
+| Field | Type | Required | Description |
629
+|---------------|--------|----------|---------------------------------------------------------------------------------------------------|
630
+| `description` | string | no | Human-readable description shown in dashboards and alerts. |
631
+| `family` | string | no | Chart grouping path (slashes `/` define hierarchy). Helps organize charts by system or subsystem. |
632
+| `unit` | string | no | Display unit, e.g. `"bit/s"`, `"%"`, `"{status}"`, `"Cel"`. |
633
+| `type` | string | no | Optional chart style override: `line`, `area`, or `stacked`. Defaults depend on metric type. |
634
+
635
## Adding Tags to Metrics
636
637
Tags add **context and identity** to SNMP metrics.