Telegraf SNMP Lookup 处理器插件按表索引通过 SNMP 为指标补充标签【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本指南完整讲解 Telegraf 的processors.snmp_lookup处理器插件它会依据指标上携带的 SNMP Agent 地址与表行索引主动查询设备 MIB 表如 ifTable / ifXTable将查询结果以标签形式补充到指标上实现接口号 → 接口名这类富化场景。读完本文你将掌握该插件的全部配置参数、缓存与并发机制、源码级工作流程以及如何用它替代processors.ifname实现 ifDescr 回退逻辑。插件源码位于 plugins/processors/snmp_lookup。插件定位与典型场景snmp_lookup是一个流式处理器Streaming Processor在 Telegraf v1.30.0 引入平台支持为 allLinux / Windows / macOS 均可类型标签为 annotation注解类。它解决的问题很具体许多 SNMP 采集场景中指标只带有数字形式的表索引例如接口索引ifIndex2而用户希望看到人类可读的名称例如ifNameeth0。传统做法是把名称查询逻辑写死在各采集插件中snmp_lookup则将通过 SNMP 查表、把结果回填成标签这一能力独立为通用处理器任何上游指标只要带有 agent 与 index 两个标签就能复用同一套查询、缓存和并发机制。例如一条原始指标foo,index2,source127.0.0.1 field123经过插件处理后变成foo,ifNameeth0,index2,source127.0.0.1 field123插件在 lookup.go 中通过processors.AddStreaming(snmp_lookup, ...)注册默认agent_tag source、index_tag index即从指标的source标签取 Agent 地址、从index标签取表行索引。完整配置与参数详解插件配置文件为 sample.conf由//go:embed sample.conf嵌入作为SampleConfig()返回。下面逐项说明# Lookup extra tags via SNMP based on the table index [[processors.snmp_lookup]] ## Name of tag of the SNMP agent to do the lookup on # agent_tag source ## Name of tag holding the table row index # index_tag index ## Timeout for each request. # timeout 5s ## SNMP version; can be 1, 2, or 3. # version 2 ## SNMP community string. # community public ## Number of retries to attempt. # retries 3 ## The GETBULK max-repetitions parameter. # max_repetitions 10 ## SNMPv3 authentication and encryption options. ## ## Security Name. # sec_name myuser ## Authentication protocol; one of MD5, SHA, or . # auth_protocol MD5 ## Authentication password. # auth_password pass ## Security Level; one of noAuthNoPriv, authNoPriv, or authPriv. # sec_level authNoPriv ## Context Name. # context_name ## Privacy protocol used for encrypted messages; one of DES, AES or . # priv_protocol ## Privacy password used for encrypted messages. # priv_password ## The maximum number of SNMP requests to make at the same time. # max_parallel_lookups 16 ## The amount of agents to cache entries for. If limit is reached, ## oldest will be removed first. 0 means no limit. # max_cache_entries 100 ## Control whether the metrics need to stay in the same order this plugin ## received them in. If false, this plugin may change the order when data is ## cached. If you need metrics to stay in order set this to true. Keeping the ## metrics ordered may be slightly slower. # ordered false ## The amount of time entries are cached for a given agent. After this period ## elapses if tags are needed they will be retrieved again. # cache_ttl 8h ## Minimum time between requests to an agent in case an index could not be ## resolved. If set to zero no request on missing indices will be triggered. # min_time_between_updates 5m ## List of tags to be looked up. [[processors.snmp_lookup.tag]] ## Object identifier of the variable as a numeric or textual OID. oid IF-MIB::ifName ## Name of the tag to create. If not specified, it defaults to the value of oid. ## If oid is numeric, an attempt to translate the numeric OID into a textual OID ## will be made. # name ## Apply one of the following conversions to the variable value: ## ipaddr: Convert the value to an IP address. ## enum: Convert the value according to its syntax in the MIB. ## displayhint: Format the value according to the textual convention in the MIB. ## # conversion 定位标签agent_tag 与 index_tag插件需要两条信息来定位要查询的行agent_tag承载 SNMP Agent 地址IP 或主机名的标签名默认sourceindex_tag承载 MIB 表行索引的标签名默认index。处理逻辑见 lookup.goAdd()会先取m.GetTag(l.AgentTag)取不到或取不到IndexTag时记录 Warn 日志Agent tag missing/Index tag missing并原样透传该指标不丢弃、不等待保证没有查询条件的数据仍然继续流动。SNMP 连接参数通用客户端配置timeout默认5s单次请求超时、retries默认 3 次重试、versionSNMP v1/v2/v3默认 2、communityv1/v2c 团体名默认public、max_repetitionsGETBULK 单次批量获取的最大重复次数默认 10均来自公共 SNMP 客户端配置默认值定义在 plugins/common/snmp/config.go 的DefaultClientConfig()。SNMPv3 支持sec_name安全名、auth_protocolMD5/SHA、auth_password认证口令、sec_levelnoAuthNoPriv / authNoPriv / authPriv、context_name上下文名、priv_protocolDES/AES、priv_password加密口令。其中auth_password与priv_password支持来自 Secret Store 的密钥引用具体用法见 docs/CONFIGURATION.md 中关于 secret store secrets 的说明。缓存与并发参数SNMP 查询是网络往返为降低对 Agent 的负载插件内置三层控制参数max_parallel_lookups默认 16并发查询的 Agent 数量上限。实现上使用 pond 工作池且保留workers/21个最小常驻 worker见 store.go兼顾峰值吞吐与连接开销max_cache_entries默认 100缓存的不同 Agent 条目数上限0 表示不限制达到上限时按最旧优先淘汰cache_ttl默认8h单个 Agent 的缓存有效期过期后再有查询需求会重新拉取min_time_between_updates默认5m当指标索引在缓存中未命中例如热插拔新增了接口时两次向该 Agent 发起更新请求的最小间隔用于防止持续刷无效请求设为 0 则完全禁止对未命中索引触发新请求此时未命中索引将保持原样输出ordered默认false是否保持指标处理前后的顺序一致。开启后插件会等待前面的指标先被解析可能略微降低吞吐但对顺序敏感的下游输出是必要的详见下文 backlog 机制。tag 子表要查询哪些 OID[[processors.snmp_lookup.tag]]定义要查询的 MIB 变量可重复声明多个oid必填。可以是数字形式如.1.3.6.1.2.1.31.1.1.1.1或文本形式如IF-MIB::ifName插件通过 gosmi 翻译器统一解析为数字 OID见 lookup.go 的初始化流程name可选。生成的标签名缺省时取 OID 文本名若 oid 为数字插件会尝试将其翻译为文本 OID 作为标签名conversion可选。取值转换方式支持ipaddr转为 IPv4/IPv6 地址、enum按 MIB 语法把枚举值转成文本、displayhint按 MIB 文本约定格式化。这些转换与inputs.snmp等插件共用同一套 Field.Conversion 实现例如ipaddr会把 4 字节/16 字节值解析为 IP见 field_test.go 中 ipaddr 用例abcd→97.98.99.100。注意enum与displayhint依赖 gosmi 翻译器支持。典型示例一ifName 查询这是最基础、最常用的配置——为带source与index标签的指标查询接口名[[processors.snmp_lookup]] agent_tag source index_tag index [[processors.snmp_lookup.tag]] oid IF-MIB::ifName效果- foo,index2,source127.0.0.1 field123 foo,ifNameeth0,index2,source127.0.0.1 field123测试 lookup_test.go 的TestAdd验证了缓存命中index123 →ifNameeth123、缺 source/index 标签透传、未命中索引原样输出等全部分支TestExpiry则验证了缓存过期后重新发起查询Agent 被查询次数从 1 增至 2。典型示例二替换 processors.ifname 并实现 ifDescr 回退processors.ifname是早期专门用于接口号 → 接口名的处理器见 plugins/processors/ifname/README.md其内部固定先查 ifXTable 的 ifName失败后回退到 ifTable 的 ifDescr见 ifname.go。snmp_lookup用两个 tag 子表即可复刻这一回退语义[[processors.snmp_lookup]] agent_tag agent index_tag ifIndex [[processors.snmp_lookup.tag]] oid .1.3.6.1.2.1.2.2.1.2 # IF-MIB::ifDescr name ifName [[processors.snmp_lookup.tag]] oid .1.3.6.1.2.1.31.1.1.1.1 # IF-MIB::ifName name ifName效果注意输出中不再出现ifIndex因为ifIndex同时作为index_tag与已存在的标签保留- foo,agent127.0.0.1,ifIndex2 field123 foo,agent127.0.0.1,ifIndex2,ifNameeth0 field123这里两个子表共用name ifName先查询 ifDescr.1.3.6.1.2.1.2.2.1.2以获取接口描述多数现代设备同时支持 ifXTable插件随后用 ifName.1.3.6.1.2.1.31.1.1.1.1覆盖同名标签——效果等价于ifName 优先、ifDescr 兜底。相比processors.ifname本插件允许你自定义任意 MIB 表而不局限于接口名场景。源码级工作流程缓存、回退与顺序保证插件处理一条指标的完整链路可以拆解为四个环节源码集中在 lookup.go、store.go、backlog.go1. 入队backlog与查缓存Add()先把指标推入 backlog 队列记录 agent、index 与待解析指标再调用cache.lookup(agent, index)。若缓存命中且索引存在立即通知 backlog 解析若缓存缺失则将 Agent 更新任务提交给工作池。2. Agent 更新updateAgentupdateAgent()为 Agent 建立 SNMP 连接snmp.NewWrapperSetAgentConnect随后table.Build(conn, true)一次性 walk 整张 MIB 表把所有行转换为index → {tag: value}的映射tagMapRows并记录本次查询时间createdlookup.go。3. 缓存与防抖store查询结果写入 expirable LRU 缓存容量max_cache_entries、TTLcache_ttl。当索引未命中时若距离上次查询已超过min_time_between_updates则立即重新查询否则把更新请求登记为延迟任务deferredUpdates由定时器在到期后执行同一 Agent 通过 inflight 标志去重避免并发重复查询store.go。4. 回填与顺序保证backlogresolve()遍历队列为匹配 agent 且索引命中的指标逐个AddTag在ordered false时已解析指标可立即放行因此输出顺序可能因各 Agent 响应快慢而变化在ordered true时队列中任一未解析指标之前的所有已解析指标都被扣留直到其前面全部解析完毕才按原顺序整体放行backlog.go。停机时Stop()会停止工作池、清空缓存并将 backlog 中仍未解析的指标全部原样输出同时在日志中提示 Added N unresolved metrics due to processor stop!避免数据丢失lookup.go。测试 lookup_test.go 中的TestNoReenqueAfterStop与TestStopWithTaskInWorkerPool专门回归了停止后不向工作池追加任务停止时工作池仍有任务不产生死锁两类边界问题可见其并发处理在实现上是经过严谨验证的。使用注意事项性能前提该插件按整表 walk 的方式查询每次更新拉取整张 MIB 表而非单行 GET对 Agent 有一定网络与 CPU 开销务必配合cache_ttl、max_parallel_lookups、min_time_between_updates将请求频率控制在合理范围缓存淘汰max_cache_entries 0表示不限制但缓存条目过多会占用内存达到上限按最旧优先淘汰被淘汰的 Agent 下次遇到新指标时会重新查询顺序敏感场景若下游输出依赖指标到达顺序例如某些数据库时序写入应设置ordered true并接受其带来的轻微性能代价依赖 MIB 翻译enum、displayhint转换依赖 gosmi 翻译器与本地 MIB 库如果设备无法翻译 OID建议显式使用数字 OID避免解析失败导致整个标签查询失败密钥安全v3 口令建议通过 Secret Store 引用而非明文写入配置文件详见 docs/CONFIGURATION.md。小结processors.snmp_lookup将SNMP 查表富化指标从各采集插件中抽离为通用能力只需在指标上携带 agent 与 index 两个标签即可用一行tag子表配置完成任意 MIB 表的标签回填。它同时内置了 LRU 缓存、并发工作池、缺失索引防抖、可选顺序保证与优雅停机数据保护既能作为processors.ifname的替代方案且支持 ifDescr 回退也是处理接口名、端口状态描述、硬件型号等 SNMP 富化需求的通用基础组件。相关实现与测试可进一步阅读 plugins/processors/snmp_lookup 与公共 SNMP 库 plugins/common/snmp。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考