f3509c5cf · cryptotaxi247/netdata · siGit Code & Deploy

@@ -21,17 +21,24 @@ Module: snmp

21

22 ## Overview

23

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

43

44

@@ -45,11 +52,13 @@ This collector supports collecting metrics from multiple instances of this integ

52

53 #### Auto-Detection

54

48 -SNMP service discovery is a dedicated component that automatically scans configured networks to find SNMP-enabled devices.

55 +SNMP service discovery can automatically scan configured networks and feed the SNMP collector with discovered devices.

56

50 -- This feature is disabled by default and requires explicit user configuration to activate.

51 -- 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.

52 -- Discovered devices are automatically made available to the SNMP collector for monitoring.

57 +- Disabled by default; enable and configure explicitly.

58 +- Supports single IPs, ranges, and CIDR blocks (up to 512 IPs per subnet).

59 +- Uses the provided SNMP credentials (v1/v2c/v3) to probe devices.

60 +- Caches discovery results (configurable) to reduce network load.

61 +- At collection time, each discovered device is matched to the appropriate profile based on its `sysObjectID`, `sysDescr`, and the profile’s selector rules.

62

63 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).

64

@@ -67,60 +76,16 @@ The default configuration for this integration does not impose any limits on dat

76

77 #### Performance Impact

78

70 -**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.

79 +**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.

80

72 -**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.

81 +**Concurrent polling**: Parallel access by multiple tools may cause missed counters on some devices. Increase the collection interval (`update_every`) to reduce request pressure.

82

83

84 ## Metrics

85

77 -Metrics grouped by *scope*.

78 -

79 -The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

80 -

81 -The metrics that will be collected are defined in the configuration file.

82 -

83 -### Per snmp device

84 -

85 -These metrics refer to the SNMP device.

86 -

87 -Labels:

88 -

89 -| Label | Description |

90 -|:-----------|:----------------|

91 -| sysName | 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)). |

86 +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.

87

93 -Metrics:

94 -

95 -| Metric | Dimensions | Unit |

96 -|:------|:----------|:----|

97 -| snmp.device_uptime | uptime | seconds |

98 -

99 -### Per network interface

100 -

101 -Network interfaces of the SNMP device being monitored. These metrics refer to each interface.

102 -

103 -Labels:

104 -

105 -| Label | Description |

106 -|:-----------|:----------------|

107 -| sysName | 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)). |

108 -| ifDescr | 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)). |

109 -| ifName | 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)). |

110 -| ifType | 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)). |

111 -

112 -Metrics:

113 -

114 -| Metric | Dimensions | Unit |

115 -|:------|:----------|:----|

116 -| snmp.device_net_interface_traffic | received, sent | kilobits/s |

117 -| snmp.device_net_interface_unicast | received, sent | packets/s |

118 -| snmp.device_net_interface_multicast | received, sent | packets/s |

119 -| snmp.device_net_interface_broadcast | received, sent | packets/s |

120 -| snmp.device_net_interface_errors | inbound, outbound | errors/s |

121 -| snmp.device_net_interface_discards | inbound, outbound | discards/s |

122 -| snmp.device_net_interface_admin_status | up, down, testing | status |

123 -| snmp.device_net_interface_oper_status | up, down, testing, unknown, dormant, not_present, lower_layer_down | status |

88 +If `ping.enabled` is true, ICMP latency/packet-loss charts are also provided (or exclusively, when `ping_only: true`).

89

90

91

@@ -151,9 +116,9 @@ UI configuration requires paid Netdata Cloud plan.

116 #### Prepare the SNMP device

117

118 Before configuring the collector:

154 -- Enable the SNMP service on the target device (through its management interface).

155 -- Make sure the device is reachable from the Netdata node on port 161/UDP.

156 -- Have ready the required connection details: IP address, SNMP version, and either a community string (v1/v2c) or user credentials (v3).

119 +- Enable the SNMP service on the target device (via its management interface).

120 +- Ensure the device is reachable from the Netdata node on UDP/161.

121 +- Gather connection details: IP/DNS, SNMP version, and either a community (v1/v2c) or v3 credentials (user, auth/priv).

122

123

124

@@ -186,12 +151,12 @@ The following options can be defined globally: update_every, autodetection_retry

151 | | options.timeout | SNMP request/response timeout. | 5 | no |

152 | | options.max_repetitions | Controls how many SNMP variables to retrieve in a single GETBULK request. | 25 | no |

153 | | options.max_request_size | Maximum number of OIDs allowed in a single GET request. | 60 | no |

189 -| **Ping** | ping_only | 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). | no | no |

154 +| **Ping** | ping_only | Collect only ICMP round-trip metrics and skip periodic SNMP polling. A minimal SNMP sysInfo probe still runs at setup for naming/labels/metadata. | no | no |

155 | | ping.enabled | Enable ICMP round-trip measurements (runs alongside SNMP). When disabled, no ping metrics are collected. | yes | no |

156 | | ping.privileged | Use raw ICMP (privileged). If false, unprivileged mode is used. | yes | no |

157 | | ping.packets | Number of ping packets to send per iteration. | 3 | no |

158 | | ping.interval | Interval between sending ping packets. | 100ms | no |

194 -| **Profiles** | manual_profiles | Profiles to apply if automatic detection cannot be used. | [] | no |

159 +| **Profiles** | manual_profiles | A list of profiles to force-apply when auto-detection cannot be used. | [] | no |

161 | | vnode_device_down_threshold | Number of consecutive failed data collections before marking the device as down. | 3 | no |

162 | | vnode.guid | A unique identifier for the Virtual Node. If not set, a GUID will be automatically generated from the device's IP address. | | no |

@@ -289,6 +254,8 @@ In this example:

254 - the SNMP community is `public`.

255 - we will update the values every 10 seconds.

256

257 +Profiles are auto-selected at runtime

258 +

259

260 <details open><summary>Config</summary>

261

Regenerate integrations docs (#21079)