Telegraf gNMI Listener 的 Nokia dial-out Telemetry 支持:GRPC 服务端实现与配置指南
Telegraf gNMI Listener 的 Nokia dial-out Telemetry 支持:GRPC 服务端实现与配置指南
导读
本文聚焦于 Telegraf 的 gnmi_listener 输入插件 中针对 Nokia(诺基亚)SR OS 设备的 dial-out telemetry(拨号遥测)支持。该功能通过一个由 nokia 子包实现的 gRPC 服务端,接收 Nokia 设备主动推送的 gNMI SubscribeResponse 消息,将设备遥测数据转化为 Telegraf 指标。读完本文,你将理解 Nokia dial-out 协议的 gRPC 接口定义与 Publish 双向流处理逻辑、如何通过 go generate 更新 protobuf 与生成的 Go 代码、如何在 Telegraf 中配置 [[inputs.gnmi_listener]] 并启用 Nokia 协议,以及 TLS 加密与常见排障策略。
Nokia dial-out telemetry:从设备主动推送到 Telegraf
传统的 gNMI 采集采用 dial-in(拨入) 模式:采集器作为 gNMI 客户端主动连接网络设备,发起 Subscribe 订阅请求,设备返回数据。而 Nokia SR OS 等设备支持的 dial-out(拨出) 模式则相反——设备作为 gNMI 客户端,主动向预先配置好的采集端发起连接并持续推送遥测数据。
正如 nokia/README.md 所述:
This package implements the GRPC server for Nokia devices to support dial-out telemetry available in Nokia SR OS (and potentially other) devices.
即 gnmi_listener 的 nokia 子包在 Telegraf 侧扮演 gRPC 服务端角色,等待 Nokia 设备连接并将数据推送进来。这正是 gnmi_listener 被归类为 service input 的原因——它不是按固定 interval 主动轮询,而是启动一个常驻服务监听端口,等待外部事件(设备推送)发生。根据 service input 说明,这类插件有两个关键差异:
- 全局或插件级别的
interval设置可能不生效; - CLI 选项
--test、--test-wait和--once可能不会为该插件产生输出。
源码剖析:Nokia gRPC 服务端的实现
目录结构与核心文件
plugins/inputs/gnmi_listener/
├── gnmi_listener.go # 插件主入口,负责启动 gRPC server
├── sample.conf # 插件样例配置(嵌入为 SampleConfig)
├── gnmi_protos/ # 通用 gNMI protobuf(gnmi.proto、gnmi_ext.proto)
└── nokia/
├── README.md # Nokia 支持说明(本文主题文档)
├── nokia-dialout-telemetry.proto # Nokia 定义的 gRPC 服务协议
├── nokia-dialout-telemetry.pb.go # protoc 生成的协议代码
├── nokia-dialout-telemetry_grpc.pb.go # protoc 生成的 gRPC 代码
└── server.go # gRPC 服务端实现
协议定义:nokia-dialout-telemetry.proto
Nokia 协议文件 定义了整个 dial-out 通信契约,其核心内容如下:
syntax = "proto3";
import "gnmi.proto";
package Nokia.SROS;
option go_package = "github.com/influxdata/telegraf/plugins/inputs/gnmi_listener/nokia";
service DialoutTelemetry {
rpc Publish(stream gnmi.SubscribeResponse) returns (stream gnmi.SubscribeRequest);
}
关键信息:
- 服务名为
DialoutTelemetry,方法为Publish; - 入参是
stream gnmi.SubscribeResponse,出参是stream gnmi.SubscribeRequest,即双向流式 RPC——设备持续向服务端流式推送SubscribeResponse,服务端则回送空的SubscribeRequest作为确认; - 它复用了 OpenConfig 的标准
gnmi.proto(位于 gnmi_protos/),说明 Nokia dial-out 推送的 payload 本质仍是标准 gNMI 消息,只是传输方式由"采集器拉取"变成了"设备推送"。
服务端实现:server.go
Nokia 服务端实现 的核心逻辑清晰,几个关键点如下:
//go:generate protoc --proto_path=../gnmi_protos:. --go_out=. --go-grpc_out=. \
// --go_opt=paths=source_relative --go-grpc_opt=paths=source_relative \
// nokia-dialout-telemetry.proto
server 结构体组合了 UnimplementedDialoutTelemetryServer(由 protoc 生成,保证向前兼容),并持有一个 common_gnmi.Handler——这是 Telegraf 统一处理 gNMI 消息、将 SubscribeResponse 转换为指标的核心处理器。
Publish 方法实现了完整的 dial-out 处理循环:
func (s *server) Publish(srv grpc.BidiStreamingServer[gnmi.SubscribeResponse, gnmi.SubscribeRequest]) error {
ctx := srv.Context()
for ctx.Err() == nil {
// Wait for data
response, err := srv.Recv()
...
// Determine the message source
source := "unknown"
if p, ok := peer.FromContext(ctx); ok { ... }
// Call the handler
s.handler.Process(s.acc, source, response)
// Send an empty response
if err := srv.Send(&gnmi.SubscribeRequest{}); err != nil { ... }
}
return nil
}
该循环的逻辑可概括为三步:
- 接收:通过
srv.Recv()阻塞等待设备推送的SubscribeResponse; - 溯源:从 gRPC 上下文(
peer.FromContext)解析对端地址,分别处理 TCP/UDP/IP 三种地址类型,将来源 IP 作为source标记附加到指标上(无法解析时回退为"unknown"); - 处理与回执:调用
s.handler.Process(s.acc, source, response)将 gNMI 消息写入 Telegraf 指标管道,并向设备回送一个空的SubscribeRequest作为流式确认。
当 Recv 返回 io.EOF(设备正常关闭流)或上下文取消时,循环退出并返回 nil;其他错误则包装为 "aborted gNMI listener" 返回。
插件主入口如何装配 Nokia 实现
gnmi_listener.go 是插件的装配层:
Init()中:Address默认值为localhost:57400;Protocol为空时默认置为"nokia"(目前"nokia"也是唯一合法取值,其它值会返回invalid 'protocol'错误);若配置了 TLS 则通过grpc.Creds(credentials.NewTLS(...))装配到grpc.ServerOption;最后创建统一的common_gnmi.Handler(默认测量名为gnmi);Start()中:根据Protocol选择实现(当前仅有nokia.New(acc, g.handler, g.Log)),通过net.Listen("tcp", address)监听端口,创建grpc.NewServer并调用impl.Register(g.server)注册服务,随后在 goroutine 中Serve;Stop()调用GracefulStop()优雅停机;Gather()为空实现(数据完全来自设备推送)。
从源码结构可以推断,serverImplementation 接口(Register(*grpc.Server))的设计为将来支持更多厂商的 dial-out 协议预留了扩展点。
更新协议文件与重新生成 Go 代码
Nokia 协议文件来源于 Nokia 官方仓库(7x50_protobufs),Telegraf 将其拷贝到 nokia/ 目录并受 Nokia 许可条款约束。当需要升级协议定义或重新生成 Go 代码时,按 nokia/README.md 的说明,在仓库根目录执行:
go generate
即可根据 server.go 顶部的 //go:generate 指令重新运行 protoc,产出新的 nokia-dialout-telemetry.pb.go 与 nokia-dialout-telemetry_grpc.pb.go。注意该命令要求环境中已安装 protoc 及 protoc-gen-go、protoc-gen-go-grpc 工具链,且 --proto_path 指向 gnmi_protos 目录以解析 gnmi.proto 的 import。
Telegraf 配置:启用 Nokia dial-out 协议
以下完整配置来自插件的 sample.conf,可直接复制使用:
# gNMI dial-out telemetry plugin
[[inputs.gnmi_listener]]
## Address and port of the gNMI GRPC server
address = "localhost:57400"
## Protocol to use, available options:
## nokia -- Nokia SR OS dial-out protocol
# protocol = "nokia"
## Emit a metric for "delete" messages
# emit_delete_metrics = false
## Enable to get the canonical path as field-name
# canonical_field_names = false
## Remove leading slashes and dots in field-name
# trim_field_names = false
## Prefix tags from path keys with the path element
# prefix_tag_key_with_path = false
## Guess the path-tag if an update does not contain a prefix-path
## Supported values are
## none -- do not add a 'path' tag
## common path -- use the common path elements of all fields in an update
## subscription -- use the subscription path
# path_guessing_strategy = "none"
## Vendor specific options
## This defines what vendor specific options to load.
## * Juniper Header Extension (juniper_header): some sensors are directly managed by
## Linecard, which adds the Juniper GNMI Header Extension. Enabling this
## allows the decoding of the Extension header if present. Currently this knob
## adds component, component_id & sub_component_id as additional tags
# vendor_specific = []
## YANG model paths for decoding IETF JSON payloads
## Model files are loaded recursively from the given directories. Disabled if
## no models are specified.
# yang_model_paths = []
## Used for TLS server certificate authentication
# tls_cert = "/path/to/certfile"
## Used for TLS server certificate authentication
# tls_key = "/path/to/keyfile"
## Password for encrypted key files
# tls_key_pwd = ""
## CA certificates used for verifying client certificates
# tls_allowed_cacerts = []
## List of ciphers to accept, by default all secure ciphers will be accepted
## Use "all", "secure" and "insecure" to add all support ciphers, secure
## suites or insecure suites respectively.
# tls_cipher_suites = ["secure"]
## Minimal TLS version to accept by the server
# tls_min_version = "TLS12"
## Maximum TLS version to accept by the server
# tls_max_version = ""
## Whitelist for certificate DNS names to accept
# tls_allowed_dns_names = []
参数说明
| 参数 | 默认值 | 作用 |
|---|---|---|
address |
localhost:57400 |
gNMI gRPC 服务端监听地址与端口,需与 Nokia 设备上配置的 dial-out 目标一致 |
protocol |
nokia |
协议选择,目前仅支持 nokia(Nokia SR OS dial-out 协议) |
emit_delete_metrics |
false |
是否为 gNMI 的 delete 消息也生成指标 |
canonical_field_names |
false |
是否使用规范化路径作为字段名 |
trim_field_names |
false |
是否去除字段名开头的斜杠与点 |
prefix_tag_key_with_path |
false |
是否用路径元素为路径键标签加前缀 |
path_guessing_strategy |
none |
update 消息缺少 prefix-path 时的路径标签推断策略:none(不加 path 标签)、common path(取该 update 内所有字段的公共路径元素)、subscription(使用订阅路径) |
vendor_specific |
[] |
厂商扩展选项,如 juniper_header(解码 Juniper GNMI Header Extension,附加 component、component_id、sub_component_id 标签) |
yang_model_paths |
[] |
解码 IETF JSON payload 所需的 YANG 模型目录(递归加载),未指定则禁用 |
tls_cert / tls_key |
空 | 服务端 TLS 证书与私钥路径 |
tls_key_pwd |
空 | 加密私钥文件的密码 |
tls_allowed_cacerts |
[] |
用于验证客户端证书的 CA 证书 |
tls_cipher_suites |
["secure"] |
接受的密码套件,支持 all、secure、insecure 或具体套件名 |
tls_min_version / tls_max_version |
TLS12 / 空 |
服务端接受的最低/最高 TLS 版本 |
tls_allowed_dns_names |
[] |
允许的客户端证书 DNS 名称白名单 |
需要说明的是:emit_delete_metrics 至 yang_model_paths 这些选项来源于嵌入在插件中的 handler.conf,由统一的 common_gnmi.HandlerConfig 处理;TLS 系列选项则由 common_tls.ServerConfig 提供并用于构建 gRPC 凭据。这些选项对所有使用该 Handler 的 gNMI 插件保持一致,体现出 Telegraf 对协议处理逻辑的复用设计。
支持的 Nokia 设备
根据 gnmi_listener README 的说明,nokia 协议支持具备 dial-out telemetry 能力的 Nokia SR OS 平台,包括:
- 7250 Interconnect Router (IXR)
- 7450 Ethernet Service Switch (ESS)
- 7750 Service Router (SR)
- 7950 Extensible Routing System (XRS)
- Virtualized Service Router (VSR)
TLS 安全传输:mTLS 与单向 TLS 配置示例
dial-out 场景下设备主动连入采集端,网络边界与身份验证尤为重要。仓库测试用例给出了两种 TLS 配置范本:
单向 TLS(服务端认证) —— nokia_tls/telegraf.conf:
[inputs.gnmi_listener]
## Used for TLS server certificate authentication
tls_cert = "../../../testutil/pki/servercert.pem"
## Used for TLS server certificate authentication
tls_key = "../../../testutil/pki/serverkey.pem"
双向 TLS(mTLS) —— nokia_mtls/testcases 中,除了服务端证书外,还通过 tls_allowed_cacerts 配置客户端证书校验、通过 tls_allowed_dns_names 校验客户端证书中的 DNS 名称,实现设备身份的强认证。测试证书可参考仓库 testutil/pki/。
生产环境中建议至少启用 TLS,并在设备侧配置正确的服务端地址与 CA 信任关系;对安全性要求高的场景,使用 mTLS 校验每个拨入设备的身份。
指标生成与输出示例
当 gNMI 消息到达后,每条 gNMI 消息会生成一个测量(measurement):SubscribeResponse Update 消息中的叶子(leaf)条目成为测量中的字段(field),叶子路径上的 PathElement key 则作为标签(tag)附加到字段上。上述 Handler 相关的路径与命名选项(canonical_field_names、trim_field_names、prefix_tag_key_with_path、path_guessing_strategy 等)正是在这一环节发挥作用。
以 OpenConfig 接口计数器遥测为例,gnmi_listener README 给出的输出形态如下:
gnmi,path=openconfig-interfaces:/interfaces/interface/state/counters,host=linux,name=MgmtEth0/RP0/CPU0/0,source=10.49.234.115,descr/description=Foo in-multicast-pkts=0i,out-multicast-pkts=0i,out-errors=0i,out-discards=0i,in-broadcast-pkts=0i,out-broadcast-pkts=0i,in-discards=0i,in-unknown-protos=0i,in-errors=0i,out-unicast-pkts=0i,in-octets=0i,out-octets=0i,last-clear="2019-05-22T16:53:21Z",in-unicast-pkts=0i 1559145777425000000
可见测量名 gnmi 上同时带有 path(订阅路径)、host、name(接口名)以及 source(由服务端从对端地址解析出的设备 IP)等标签,字段则对应接口计数器的各项数值。
排障:缺失 path 标签的处理
部分设备(如 Arista)在 update 中省略 prefix 并直接在 update 内指定路径,会导致生成指标缺少 path 标签。此时应设置:
path_guessing_strategy = "subscription"
以订阅路径作为 path 标签;若设备完全省略 prefix,则可改用:
path_guessing_strategy = "common path"
通过取 update 内所有字段路径的公共前缀来推断 path 标签。结合 source 标签可以快速定位来自哪台设备的数据异常。
许可说明
Nokia 协议文件及其生成的 Go 代码遵循 Nokia 的许可条款:Nokia 保留规范的所有权与知识产权,同时授予所有相关方非独占许可,可在管理 Nokia 产品时免费使用和分发未经修改的规范副本(须保留版权声明与许可文本),规范按"原样"提供、不作任何明示或暗示的担保。详情见 nokia/README.md 的 License 一节。
总结
Telegraf 的 gnmi_listener 插件通过 nokia 子包为 Nokia SR OS 设备提供了开箱即用的 dial-out telemetry 采集能力:设备作为客户端主动拨入,Telegraf 侧运行 gRPC 双向流服务端接收 SubscribeResponse,统一交由 common_gnmi.Handler 转换为带 path、source 等标签的指标。配合 go generate 的协议更新机制、TLS/mTLS 安全配置、path_guessing_strategy 排障手段以及可扩展的 serverImplementation 接口设计,这套实现既务实又具备良好的演进空间,是网络设备拨号遥测接入监控体系的可参考方案。
进一步阅读:gnmi_listener 插件 README、sample.conf、服务端实现、测试用例目录、通用 gNMI Handler 配置。