docs: update SNMP collector metadata to reflect profile-based collection (#21078)
Ilya Mashchenko committed
Sep 30, 2025 at 23:32 UTC
b508f7b75a36c26888c0b7d0367e0871c7799dc2
1 file changed
+35
-108
src/go/plugin/go.d/collector/snmp/metadata.yaml
+35
-108
@@ -21,17 +21,24 @@ modules:
21
overview:
22
data_collection:
23
metrics_description: |
24
- This SNMP collector discovers and gathers statistics for network interfaces on SNMP-enabled devices:
24
+ This SNMP collector discovers and monitors SNMP-enabled devices using **profiles**.
25
26
- - Traffic
27
- - Packets (unicast, multicast, broadcast)
28
- - Errors
29
- - Discards
30
- - Administrative and operational status
26
+ A *profile* declares:
27
+ - device selectors (e.g. `sysObjectID`, `sysDescr`) for auto-matching,
28
+ - which OIDs to collect (scalars and tables),
29
+ - how to label rows (metric tags), and
30
+ - chart/metric metadata (units, families, types), including optional **virtual metrics**.
31
32
- Additionally, it collects overall device uptime.
32
+ At runtime, the collector:
33
+ 1) identifies the device by reading standard system OIDs (e.g. `sysObjectID`, `sysDescr`),
34
+ 2) picks the best-matching profile(s), and
35
+ 3) collects exactly the metrics defined by those profiles.
36
34
- It is compatible with all SNMP versions (v1, v2c, and v3) and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.
37
+ Because profiles vary per vendor/model/OS, there is **no fixed list of metrics** in this page. Netdata renders the charts that each matched profile defines (interfaces, optics, CPU/mem, environment, VLANs, etc., depending on the device).
38
+
39
+ The collector optionally runs **ICMP round-trip (ping)** alongside SNMP for availability and latency. A `ping_only` mode is available to skip periodic SNMP polling.
40
+
41
+ SNMP versions v1, v2c, and v3 are supported, implemented via the [gosnmp](https://github.com/gosnmp/gosnmp) library.
42
method_description: ""
43
supported_platforms:
44
include: []
@@ -42,11 +49,13 @@ modules:
49
default_behavior:
50
auto_detection:
51
description: |
45
- SNMP service discovery is a dedicated component that automatically scans configured networks to find SNMP-enabled devices.
52
+ SNMP service discovery can automatically scan configured networks and feed the SNMP collector with discovered devices.
53
47
- - This feature is disabled by default and requires explicit user configuration to activate.
48
- - When enabled, it discovers devices using customizable credentials, supports various IP range formats (single IPs, ranges, CIDR) with a limit of 512 IPs per subnet, and optimizes network traffic through configurable caching of discovery results.
49
- - Discovered devices are automatically made available to the SNMP collector for monitoring.
54
+ - Disabled by default; enable and configure explicitly.
55
+ - Supports single IPs, ranges, and CIDR blocks (up to 512 IPs per subnet).
56
+ - Uses the provided SNMP credentials (v1/v2c/v3) to probe devices.
57
+ - 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.
59
60
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).
61
@@ -60,18 +69,18 @@ modules:
69
description: ""
70
performance_impact:
71
description: |
63
- **Device limitations**: Many SNMP switches and routers have limited processing power. They might not be able to report data as frequently as desired. You can monitor response times using go.d.plugin in debug mode to identify potential bottlenecks.
72
+ **Device constraints**: Many SNMP devices (e.g., access switches) have limited CPU/ASIC time for management. If you see timeouts or gaps, reduce `update_every` or `max_repetitions`, or stagger polling across devices.
73
65
- **Concurrent access**: If multiple collectors or tools access the same SNMP device simultaneously, data points might be skipped. This is a limitation of the device itself, not this collector. To mitigate this, consider increasing the collection interval (update_every) to reduce the frequency of requests.
74
+ **Concurrent polling**: Parallel access by multiple tools may cause missed counters on some devices. Increase the collection interval (`update_every`) to reduce request pressure.
75
setup:
76
prerequisites:
77
list:
78
- title: "Prepare the SNMP device"
79
description: |
80
Before configuring the collector:
72
- - Enable the SNMP service on the target device (through its management interface).
73
- - Make sure the device is reachable from the Netdata node on port 161/UDP.
74
- - Have ready the required connection details: IP address, SNMP version, and either a community string (v1/v2c) or user credentials (v3).
81
+ - Enable the SNMP service on the target device (via its management interface).
82
+ - Ensure the device is reachable from the Netdata node on UDP/161.
83
+ - Gather connection details: IP/DNS, SNMP version, and either a community (v1/v2c) or v3 credentials (user, auth/priv).
84
configuration:
85
file:
86
name: go.d/snmp.conf
@@ -201,7 +210,7 @@ modules:
210
211
- name: ping_only
212
group: Ping
204
- description: Collect only ICMP round-trip metrics and skip periodic SNMP metrics. A minimal SNMP sysInfo request is still performed when setting up the Virtual Node (for naming/labels and metadata).
213
+ description: Collect only ICMP round-trip metrics and skip periodic SNMP polling. A minimal SNMP sysInfo probe still runs at setup for naming/labels/metadata.
214
default_value: false
215
required: false
216
- name: ping.enabled
@@ -225,10 +234,9 @@ modules:
234
default_value: 100ms
235
required: false
236
228
-
237
- name: manual_profiles
238
group: Profiles
231
- description: Profiles to apply if automatic detection cannot be used.
239
+ description: A list of profiles to force-apply when auto-detection cannot be used.
240
default_value: "[]"
241
required: false
242
@@ -270,6 +278,8 @@ modules:
278
- the SNMP version is `2`.
279
- the SNMP community is `public`.
280
- we will update the values every 10 seconds.
281
+
282
+ Profiles are auto-selected at runtime
283
config: |
284
jobs:
285
- name: switch
@@ -306,92 +316,9 @@ modules:
316
folding:
317
title: Metrics
318
enabled: false
309
- description: The metrics that will be collected are defined in the configuration file.
319
+ description: |
320
+ 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.
321
+
322
+ If `ping.enabled` is true, ICMP latency/packet-loss charts are also provided (or exclusively, when `ping_only: true`).
323
availability: []
311
- scopes:
312
- - name: snmp device
313
- description: These metrics refer to the SNMP device.
314
- labels:
315
- - name: sysName
316
- description: "SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5))."
317
- metrics:
318
- - name: snmp.device_uptime
319
- description: SNMP device uptime
320
- unit: seconds
321
- chart_type: line
322
- dimensions:
323
- - name: uptime
324
- - name: network interface
325
- description: Network interfaces of the SNMP device being monitored. These metrics refer to each interface.
326
- labels:
327
- - name: sysName
328
- description: "SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5))."
329
- - name: ifDescr
330
- description: "Network interface description (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.2))."
331
- - name: ifName
332
- description: "Network interface name (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.31.1.1.1.1))."
333
- - name: ifType
334
- description: "Network interface type (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.3))."
335
- metrics:
336
- - name: snmp.device_net_interface_traffic
337
- description: SNMP device network interface traffic
338
- unit: kilobits/s
339
- chart_type: area
340
- dimensions:
341
- - name: received
342
- - name: sent
343
- - name: snmp.device_net_interface_unicast
344
- description: SNMP device network interface unicast packets
345
- unit: packets/s
346
- chart_type: line
347
- dimensions:
348
- - name: received
349
- - name: sent
350
- - name: snmp.device_net_interface_multicast
351
- description: SNMP device network interface multicast packets
352
- unit: packets/s
353
- chart_type: line
354
- dimensions:
355
- - name: received
356
- - name: sent
357
- - name: snmp.device_net_interface_broadcast
358
- description: SNMP device network interface broadcast packets
359
- unit: packets/s
360
- chart_type: line
361
- dimensions:
362
- - name: received
363
- - name: sent
364
- - name: snmp.device_net_interface_errors
365
- description: SNMP device network interface errors
366
- unit: errors/s
367
- chart_type: line
368
- dimensions:
369
- - name: inbound
370
- - name: outbound
371
- - name: snmp.device_net_interface_discards
372
- description: SNMP device network interface discards
373
- unit: discards/s
374
- chart_type: line
375
- dimensions:
376
- - name: inbound
377
- - name: outbound
378
- - name: snmp.device_net_interface_admin_status
379
- description: SNMP device network interface administrative status
380
- unit: status
381
- chart_type: line
382
- dimensions:
383
- - name: up
384
- - name: down
385
- - name: testing
386
- - name: snmp.device_net_interface_oper_status
387
- description: SNMP device network interface operational status
388
- unit: status
389
- chart_type: line
390
- dimensions:
391
- - name: up
392
- - name: down
393
- - name: testing
394
- - name: unknown
395
- - name: dormant
396
- - name: not_present
397
- - name: lower_layer_down
324
+ scopes: []