Skip to content

IndustryKit SNMP v3

The SNMP source uses v3 USM and performs GET requests for the configured exact numeric OIDs at the source's interval. Some OIDs from standard MIBs can be reused across devices, while vendor-specific metrics must be configured according to the device MIB or snmpwalk output. The example explicitly uses 30s to reduce polling load on the device. When interval is omitted, the program-wide default remains 10s.

Configuration hierarchy

Level Purpose
[[sources]] Defines an SNMP collection task. Repeat it to configure multiple agents.
[sources.snmp] Configures the SNMP v3 connection, USM credentials, and request options for the current source.
[[sources.snmp.points]] Defines one GET point. Each item maps one OID to one output field.

Each [[sources]] entry can contain only one protocol subtable. type = "snmp" must correspond to [sources.snmp]. field is the output field name written to the measurement, while oid identifies the object read from the device.

Configuration

[[sources]]
id = "snmp-switch"
type = "snmp"
measurement = "snmp_metrics"
interval = "30s"
tags = { device = "switch-01" }

[sources.snmp]
address = "192.0.2.50:161"
transport = "udp"
security_level = "auth_priv"
username = "<SNMP_USERNAME>"
auth_protocol = "sha256"
auth_password = "<SNMP_AUTH_PASSWORD>"
privacy_protocol = "aes"
privacy_password = "<SNMP_PRIVACY_PASSWORD>"
timeout = "2s"
retries = 1
max_oids_per_request = 32

[[sources.snmp.points]]
field = "sys_uptime"
oid = "1.3.6.1.2.1.1.3.0"
data_type = "uint"

[[sources.snmp.points]]
field = "sys_name"
oid = "1.3.6.1.2.1.1.5.0"
data_type = "string"

Options

[[sources]]

Field Default Description
id None Required and unique within the configuration. It is also added as the source_id tag.
type None Must be set to snmp.
measurement industrial Name of the reported metric measurement or log source.
interval 10s Polling interval. It must be greater than 0. For regular SNMP monitoring, explicitly setting it to 30s is recommended.
tags {} Static tags for this source.

[sources.snmp]

Field Default Description
address None Required agent address in host:port format, usually using port 161.
transport udp Transport protocol: udp or tcp.
security_level auth_priv no_auth_no_priv, auth_no_priv, or auth_priv.
username None Required for every security level. It must contain 1..32 non-NUL bytes.
auth_protocol sha256 Used when authentication is enabled: sha, sha224, sha256, sha384, or sha512.
auth_password None Required for auth_no_priv and auth_priv. It must be at least 8 bytes.
privacy_protocol aes Used by auth_priv: aes, aes192, aes256, aes192c, or aes256c.
privacy_password None Required only for auth_priv. It must be at least 8 bytes.
context_name Empty Optional context name containing at most 32 non-NUL bytes.
timeout 2s Timeout for one request. It must be greater than 0.
retries 0 Number of retries for each GET round, in the range 0..3.
max_oids_per_request 32 Number of OIDs in each GET request, in the range 1..60.

no_auth_no_priv must not include authentication or privacy fields. auth_no_priv must not include privacy fields. auth_priv requires both authentication and privacy passwords.

[[sources.snmp.points]]

Field Default Description
field None Required output field name.
category metric Output category: metric or logging.
tags {} Static tags for this point.
oid None Required exact numeric OID, with or without a leading .. It must contain 2..128 decimal segments; the first segment must be 0..2 and the second 0..39. MIB names are not supported.
data_type auto auto, int, uint, float, string, bytes, or bool.
scale 1 Multiplier used for numeric transformation.
offset 0 Numeric transformation offset. The final value is value * scale + offset.
on_change false Whether a metric is sent only when its value changes. Logging data is always sent on change.
emit_initial false Whether to send the first observed value for logging data or a metric with on_change enabled.
status info Status field used only for logging data.

Data and limitations

  • auto converts a value according to its SNMP BER type. A missing OID or conversion failure rejects only the corresponding point.
  • Devices do not all produce the same fields. The measurement and fields depend on the configured OIDs.
  • Each source must contain at least one point. The same combination of field and final tags cannot be repeated.
  • MIB parsing, walk operations, and automatic discovery are not supported.
  • SNMP v1/v2c, Trap, Inform, and SET are not supported.

Feedback

Is this page helpful?