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.