IndustryKit SNMP v3

SNMP source 使用 v3 USM，按 source 的 interval 对配置的精确数字 OID 执行 GET。标准 MIB 中部分 OID 可以跨设备复用，厂商私有指标仍需依据具体设备 MIB 或 snmpwalk 结果配置。示例显式使用 30s 以降低设备轮询压力；省略 interval 时程序的通用默认值仍为 10s。

配置层级¶

层级	作用
`[[sources]]`	定义一个 SNMP 采集任务；可重复配置多台 Agent。
`[sources.snmp]`	配置当前 source 的 SNMP v3 连接、USM 凭据和请求参数。
`[[sources.snmp.points]]`	定义一个 GET 点位；每增加一项就把一个 OID 映射为一个输出字段。

每个 [[sources]] 只能包含一个协议子表；type = "snmp" 必须与 [sources.snmp] 对应。 field 是写入 measurement 的输出字段名，oid 才是设备中被读取的对象标识。

配置¶

[[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"

参数¶

`[[sources]]`¶

字段	默认值	说明
`id`	无	必填且在配置中唯一；同时作为 `source_id` 标签。
`type`	无	必须设置为 `snmp`。
`measurement`	`industrial`	上报的指标集或日志来源名称。
`interval`	`10s`	轮询周期，必须大于 `0`；常规 SNMP 监控建议显式设置为 `30s`。
`tags`	`{}`	当前 source 的静态标签。

`[sources.snmp]`¶

字段	默认值	说明
`address`	无	必填的 Agent `host:port`，通常使用端口 `161`。
`transport`	`udp`	传输协议：`udp` 或 `tcp`。
`security_level`	`auth_priv`	`no_auth_no_priv`、`auth_no_priv` 或 `auth_priv`。
`username`	无	所有安全级别都必填，长度为 `1..32` 个非 NUL 字节。
`auth_protocol`	`sha256`	认证模式使用：`sha`、`sha224`、`sha256`、`sha384` 或 `sha512`。
`auth_password`	无	`auth_no_priv` 和 `auth_priv` 必填，至少 `8` 字节。
`privacy_protocol`	`aes`	`auth_priv` 使用：`aes`、`aes192`、`aes256`、`aes192c` 或 `aes256c`。
`privacy_password`	无	仅 `auth_priv` 必填，至少 `8` 字节。
`context_name`	空	可选上下文名称，最多 `32` 个非 NUL 字节。
`timeout`	`2s`	单次请求超时，必须大于 `0`。
`retries`	`0`	单轮 GET 的重试次数，范围为 `0..3`。
`max_oids_per_request`	`32`	每个 GET 请求的 OID 数，范围为 `1..60`。

no_auth_no_priv 不得设置认证和隐私字段；auth_no_priv 不得设置隐私字段； auth_priv 必须同时提供认证和隐私密码。

`[[sources.snmp.points]]`¶

字段	默认值	说明
`field`	无	必填的输出字段名。
`category`	`metric`	输出类型：`metric` 或 `logging`。
`tags`	`{}`	当前点位的静态标签。
`oid`	无	必填的精确数字 OID，可带或不带前导 `.`；包含 `2..128` 个十进制数字段，第一段范围为 `0..2`、第二段范围为 `0..39`，不支持 MIB 名称。
`data_type`	`auto`	`auto`、`int`、`uint`、`float`、`string`、`bytes` 或 `bool`。
`scale`	`1`	数值变换乘数。
`offset`	`0`	数值变换偏移；最终值为 `value * scale + offset`。
`on_change`	`false`	metric 是否仅在值变化时发送；logging 始终按变化发送。
`emit_initial`	`false`	对 logging 或启用 `on_change` 的 metric，是否发送首次观察值。
`status`	`info`	仅用于 logging 的状态字段。

数据与限制¶

auto 根据 SNMP BER 类型转换值；缺失 OID 或转换失败只拒绝对应点。
所有设备不会产生相同字段，measurement 和 field 取决于配置的 OID。
单个 source 至少配置一个 point；相同 field 与最终标签组合不能重复。
当前不解析 MIB，也不执行 walk 或自动发现。
当前不支持 SNMP v1/v2c、Trap、Inform 和 SET。