Nightingale 与 Categraf SNMP 插件：网络设备监控采集、仪表盘与告警实战指南

Nightingale 与 Categraf SNMP 插件：网络设备监控采集、仪表盘与告警实战指南

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale

网络设备的监控主要依赖 SNMP（简单网络管理协议）协议完成，Categraf、Telegraf、Datadog-Agent、snmp_exporter 等采集器都提供了这一能力。本文以 Nightingale 仓库中 SNMP 集成 的说明为主体，结合仓库内真实的采集配置、仪表盘与告警规则，系统讲解如何用 Categraf 的 SNMP 插件采集网络设备指标、如何在 Nightingale 中落地流量仪表盘与告警。读完本文，你将掌握"配置 OID 即采集指标"的插件核心用法、SNMPv3 认证配置、通用 OID 与厂商私有 OID 的取舍，以及从连通性测试到告警排错的全链路方法。

一、为什么用 Categraf 的 SNMP 插件

Categraf 从 v0.2.13 版本开始把 Telegraf 的 snmp 插件集成进来，官方推荐使用该插件监控网络设备。这个插件的核心逻辑非常简洁：要采集什么指标，直接配置对应的 OID 即可；而且可以把部分 OID 采集到的数据当作时序数据的标签（tag）使用，灵活度极高。

例如，把RFC1213-MIB::sysName.0采集到的设备名称作为标签，那么后续所有来自该设备的时间序列都会自动带上设备名，在仪表盘中即可按设备维度进行筛选和聚合。这种"指标 + 标签"由 OID 配置直接驱动的方式，让网络设备监控的扩展成本降到最低——新增一个指标通常只需要新增一行 OID 配置。

当然，SNMP 世界也有明显的弊端：体系内存在大量厂商私有 OID（private OID）。例如不同品牌、不同型号的设备，获取 CPU、内存利用率的 OID 往往都不一样，这就意味着不同型号的设备需要不同的采集配置，维护成本较高，需要长期的经验积累。仓库内的 collect/snmp 目录就展示了通用配置（snmp.toml）与厂商专用配置（Cisco.toml）两种形态的差异。

二、快速上手：通用 OID 采集配置详解

虽然私有 OID 繁多，但对于网络设备而言，大部分监控数据用标准 MIB（如 RFC1213-MIB、IF-MIB、UCD-SNMP-MIB）中的通用 OID 即可采集。仓库 README 给出了一个完整的通用配置示例：

interval = 120 [[instances]] agents = ["udp://172.30.15.189:161"] interval_times = 1 timeout = "5s" version = 2 community = "public" agent_host_tag = "agent_host" retries = 1 [[instances.field]] oid = "RFC1213-MIB::sysUpTime.0" name = "uptime" [[instances.field]] oid = "RFC1213-MIB::sysName.0" name = "source" is_tag = true [[instances.table]] oid = "IF-MIB::ifTable" name = "interface" inherit_tags = ["source"] [[instances.table.field]] oid = "IF-MIB::ifDescr" name = "ifDescr" is_tag = true [[instances.table.field]] oid = "IF-MIB::ifSpeed" name = "ifSpeed" [[instances.table.field]] oid = "IF-MIB::ifOperStatus" name = "ifOperStatus" [[instances.table.field]] oid = "IF-MIB::ifInOctets" name = "ifInOctets" [[instances.table.field]] oid = "IF-MIB::ifOutOctets" name = "ifOutOctets"

2.1 实例级参数

其中agents的完整格式为"<scheme://><hostname>:<port>"，scheme 可选udp、udp4、udp6、tcp、tcp4、tcp6，默认为udp；端口可省略（默认 161）。详见仓库中的 snmp.toml.example。

2.2 field 与 table：两种采集形态

• [[instances.field]]：采集单个标量 OID。上面的示例中，sysUpTime.0被命名为uptime指标；sysName.0被命名为source，并且由于设置了is_tag = true，它不再作为指标值，而是作为标签附加到同实例的所有时间序列上。
• [[instances.table]]：采集一张 SNMP 表（如IF-MIB::ifTable接口表），表格会被展开成多行时序数据。name = "interface"定义了表名，采集出的指标将以snmp_interface_*为前缀命名；inherit_tags = ["source"]表示把顶层 field 中定义的标签（如source）继承到表格的每一行序列上，这样每条接口流量序列都能知道它来自哪台设备。
• [[instances.table.field]]：定义表中要采集的列。ifDescr同样被标记为is_tag = true，作为区分不同接口的标签；ifSpeed、ifOperStatus、ifInOctets、ifOutOctets则作为普通指标值上报。

从仓库 dashboards.json 中可以看到，仪表盘实际查询的指标名即为snmp_interface_ifInOctets、snmp_interface_ifOutOctets、snmp_interface_ifDescr、snmp_interface_ifOperStatus、snmp_uptime等，与上述命名规则完全对应，这也验证了"snmp_+ 表名 +_+ 字段名"的指标命名规律。

2.3 安全提醒与仪表盘依赖

示例中的public团体字仅用于示例和测试环境。生产环境的设备应使用独立且受控的 community，或优先采用 SNMPv3（见下文）。

另外需要特别注意：本目录附带的通用流量仪表盘依赖以下标签/指标：agent_host、ifDescr、ifSpeed、ifOperStatus、ifInOctets、ifOutOctets。如果修改了agent_host_tag的名字，必须同步修改仪表盘变量，否则仪表盘将无法正确过滤和展示数据。

同时，为了兼容历史模板，可以把同一个标准 OID 以不同字段名重复采集，例如将IF-MIB::ifDescr同时命名为ifDescr与ifname，将流量计数同时命名为ifInOctets/incoming、ifOutOctets/outgoing，这样新老两套仪表盘都能命中数据（详见仓库中的 中文版 README）。

三、参数参考：snmp.toml.example 全参数解析

仓库中的 snmp.toml.example 是插件参数的权威参考，除上文已介绍的参数外，还包含以下常用项：

3.1 SNMPv3 认证与加密参数

SNMPv3 相比 v2 增加了用户认证（authentication）与数据加密（privacy）能力，示例配置中的参数含义如下：

注意：AES192、AES192C、AES256、AES256C等协议要求底层的 net-snmp 工具在编译时启用--enable-blumenthal-aes。

四、SNMPv3 认证配置示例

上面的样例是 v2 版本的配置；如果设备只开放 SNMPv3，认证配置示例如下（同样来自 README）：

version = 3 sec_name = "managev3user" auth_protocol = "SHA" auth_password = "<auth-password>" sec_level = "authPriv" priv_protocol = "AES" priv_password = "<privacy-password>"

该配置启用了"认证 + 加密"的最高安全级别（authPriv）：用 SHA 算法做身份认证，用 AES 算法对报文加密。生产环境中建议优先使用这种方式替代 v1/v2 的明文团体字。

五、深入实战：仓库中的两份参考采集配置

5.1 通用配置 snmp.toml：标准 OID 采集 CPU、内存、负载与接口

仓库 collect/snmp/snmp.toml 是一份可直接落地的通用配置，其中大量使用数字 OID来采集主机资源指标，避免了 MIB 名称解析的依赖：

agents = [ # "udp://10.206.0.16:161", ] timeout = "5s" version = 2 community = "public" agent_host_tag = "agent_hostname" retries = 3 [[instances.field]] oid = ".1.3.6.1.2.1.1.3.0" name = "uptime" [[instances.field]] oid = ".1.3.6.1.4.1.2021.11.9.0" # % name = "cpu_user" [[instances.field]] oid = ".1.3.6.1.4.1.2021.11.10.0" # % name = "cpu_sys" [[instances.field]] oid = "1.3.6.1.4.1.2021.11.11.0" # % name = "cpu_idle" [[instances.field]] oid = ".1.3.6.1.2.1.25.2.2.0" name = "mem_total" [[instances.field]] oid = ".1.3.6.1.4.1.2021.4.11.0" name = "mem_free" # network [[instances.table]] oid = "IF-MIB::ifTable" name = "interface" inherit_tags = ["source"] index_as_tag = true include_filter = ["ifIndex:2","ifIndex:4"] [[instances.table.field]] oid = "IF-MIB::ifDescr" name = "ifDescr" is_tag = true

这份配置里有两个值得注意的细节：

• 数字 OID 与符号名混用：既可以用.1.3.6.1.2.1.1.3.0，也可以用IF-MIB::ifTable这类符号名，插件都能解析。
• index_as_tag = true与include_filter：前者将表的索引列（如ifIndex）作为标签输出，便于区分同一设备上的不同接口；后者用于只采集满足条件的行（例如只采集ifIndex为 2 和 4 的接口），减少无用数据量。

该配置采集的cpu_idle、mem_total、mem_free等指标，与仪表盘中的100 - snmp_cpu_idle、(snmp_mem_max - snmp_mem_free) / snmp_mem_max * 100表达式一一对应，可直接驱动 SNMP Stats 仪表盘 中的 CPU/内存面板。

5.2 厂商专用配置 Cisco.toml：私有 OID 与值转换

仓库 collect/snmp/Cisco.toml 展示了面向具体厂商设备的私有 OID 采集方式，其中几个要点：

agents = ["udp://127.0.0.1"] timeout = "5s" version = 2 community = "public" agent_host_tag = "DCN" retries = 3 max_repetitions = 100 [[instances.field]] oid = "1.3.6.1.2.1.1.3.0" name = "sys_uptime" conversion = "float(2)" [[instances.field]] oid = "1.3.6.1.4.1.6339.100.1.11.10.0" # 厂商私有：CPU 使用率 name = "cpu_usage" [[instances.field]] oid = "1.3.6.1.4.1.6339.100.1.11.6.0" # 厂商私有：内存最大值 name = "mem_max" [[instances.field]] oid = "1.3.6.1.4.1.6339.100.1.11.7.0" # 厂商私有：内存使用量 name = "mem_use" [[instances.field]] oid = "1.3.6.1.2.1.1.5.0" name = "sys_name" is_tag = true

这里可以看到私有 OID 的典型特征：1.3.6.1.4.1.6339...中的6339就是厂商在 IANA 申请的企业号（enterprise number），不同厂商完全不同，这正是"不同型号设备需要不同配置"的根源。

此外，conversion = "float(2)"是插件提供的数据转换能力：把采集到的原始值按指定规则转换为浮点数（如把千分位/特殊编码的计数器换算成可读数值），ifSpeed列还使用了conversion = "float(6)"将接口速率转换为以 bit/s 为单位的值。这类转换在厂商私有指标中非常常见。

六、与 Nightingale 联动：仪表盘与告警规则

该集成目录（integrations/SNMP）不仅包含采集配置，还自带了一套与 Nightingale 平台配套的仪表盘、告警规则和指标字典，导入即可使用：

6.1 仪表盘（dashboards 目录）

• SNMP Stats（dashboards.json）：通用状态面板，包含 Uptime、CPU 使用率、内存使用率、每秒新建连接数、进出流量、丢包数、接口状态表等。其接口状态表对ifOperStatus的取值做了颜色映射：up(1)显示为绿色 UP、down(2)显示为红色 DOWN、testing(3)为 TESTING，一目了然。
• 网络设备详情通用仪表盘（网络设备详情通用仪表盘.json）
• 网络设备端口流量视图（网络设备端口流量视图.json）
• SNMP 网络设备状态汇总（SNMP 网络设备状态汇总.json）
• 华为网络设备详情（华为网络设备详情.json）、Juniper 网络设备详情（Juniper网络设备详情.json）等厂商专用大盘

6.2 告警规则（alerts 目录）

告警规则以 JSON 形式提供，可以直接导入 Nightingale。以 SNMP Network.json 为例，内置了三条典型告警：

• 带宽使用率过高（Bandwidth Usage Too High）：核心表达式为min_over_time(delta(snmp_network_status_incoming[3m]) * 8 / 180 / 1024 / 1024 [3m]) > snmp_network_status_speed / 1000 * 0.7 * 1024 * 1024 * 1024，即按物理端口容量的70% / 90%设置两档告警（severity 3 / 2）。表达式先把流量计数换算成 bit/s，再与ifSpeed表示的端口容量比较。
• CRC 错误（CRC Error）：delta(snmp_network_status_incoming_errors[1m]) > 100 and delta(snmp_network_status_incoming_errors[1m]) / delta(snmp_network_status_incoming_ucastpkts[1m]) > 0.001，要求 1 分钟内错误包增量大于 100 且错误率超过 0.1%（严重档 1%），用于捕捉物理链路质量问题。
• 接口 DOWN（Interface Down）：snmp_network_status_admin_status == 1 and snmp_network_status_ostatus offset 4m == 1 and min_over_time(snmp_network_status_ostatus[3m]) == 2，即管理状态为 up 但最近 3 分钟运行状态持续为 down 时告警，并带 4 分钟 offset 避免"刚 down 又 up"的抖动误报。

Network Device Health.json 则提供了设备可用性告警：

• SNMP 探测失败（设备在线）：max_over_time(snmp_icmp_up{}[3m]) == 1 and max_over_time(snmp_up{}[3m]) == 0—— 设备 ICMP 可达但 SNMP 探测持续失败，说明问题出在 SNMP 服务、ACL、UDP 161 或凭据，而非设备宕机。
• SNMP 采集中断（曾有数据）：max_over_time(snmp_up{}[1h]) == 1 unless max_over_time(snmp_up{}[10m])—— 过去 1 小时有成功采集但最近 10 分钟无任何snmp_up样本，代表采集链路整体中断（Agent 离线、配置被移除、网络中断等）。

6.3 指标字典（metrics 目录）

metrics/categraf-base.json 提供了指标的中英文释义，帮助理解各指标语义与取值：

• snmp_interface_admin_status（gauge）：接口管理状态，up(1)启用、down(2)关闭、testing(3)测试模式；
• snmp_interface_ostatus：接口运行状态，up(1)正常收发、down(2)无法工作、testing(3)测试模式；
• snmp_interface_outgoing_errors（counter）：接口发送方向的错误累计数；
• snmp_interface_outgoing_ucastpkts：接口发送方向的单播包累计数（与错误数相除可得到错包率）；
• snmp_interface_speed：接口最大传输速率，单位 bit/s。

七、采集频率与部署建议

针对 SNMP 采集，官方建议部署一个独立的 Categraf来承担网络设备采集任务，原因是不同的监控对象往往需要不同的采集频率。例如：

• 边缘交换机 5 分钟采集一次即可；
• 核心交换机可以配置得更频繁，例如 60s 或 120s。

注意：如果采集过于频繁，一些老款交换机可能会被打挂或被限流；被限流的结果就是在监控图上看到数据断点（gap）。因此在配置interval时，要结合设备性能和厂商建议做权衡，而不是一味追求高频率。

八、排错指南

要成功通过 Categraf 采集到 SNMP 数据，首先要保证Categraf 所在机器能够连通网络设备。可以用snmpget命令先做连通性与凭据验证（README 中的方法）：

snmpget -v2c -c public 172.30.15.189 RFC1213-MIB::sysUpTime.0

其中-v2c指定 SNMP 版本、-c public指定团体字、RFC1213-MIB::sysUpTime.0指定要读取的 OID。如果这条命令都执行不通，需要按顺序排查以下常见原因：

1. snmpd 服务未启动：在目标设备上确认 SNMP 服务已启用；
2. 防火墙拦截：检查设备 ACL 与中间防火墙是否放行了采集机到设备的 UDP 161 端口；
3. 命令未安装：采集机上缺少 net-snmp 工具包，安装后即可；
4. 凭据错误：团体字 / SNMPv3 用户名密码配置不正确（可再用snmpwalk做进一步验证）。

排通连通性后，如果数据仍然异常，可以对照上文的告警语义定位：ICMP 可达但 SNMP 探测失败多为凭据或 ACL 问题；曾经有数据但突然中断则优先检查采集 Agent 与采集配置。恢复后要注意历史数据缺口，盲区期间不会有告警产生。

另外，本次实测数据来自真实的 net-snmp agent，验证了标准的 CPU、内存、TCP 和接口 OID。需要强调的是：Juniper、华为等厂商专用模板虽然可以展示标准 OID 数据，但厂商私有的 CPU、内存、风扇、电源、板卡等指标，仍必须使用对应型号的 MIB 与真实硬件进行验证，这也是第 5 节中厂商私有 OID 配置必须逐型号维护的根本原因。

结语

从"配置 OID 即采集"的插件哲学，到通用 OID 与厂商私有 OID 的取舍，再到 Nightingale 中仪表盘、告警与指标字典的落地，Categraf 的 SNMP 插件为网络设备监控提供了一条低门槛、高灵活的路径。实践中建议遵循三条主线：生产环境使用 SNMPv3 或受控团体字保障安全；按设备层级差异化配置采集频率；厂商私有指标务必以真实 MIB 和实机验证为准。围绕这些要点，仓库 integrations/SNMP 下的采集配置、仪表盘与告警规则都可以作为起点直接复用，再结合自身设备型号逐步积累配置资产。

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale