Telegraf gNMI Listener 的 Nokia dial-out Telemetry 支持:GRPC 服务端实现与配置指南

原创2026-09-13 13:31:061,855 阅读
文章标签:可观测性指标监控运维云原生数据集成日志分析物联网

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 说明,这类插件有两个关键差异:

  1. 全局或插件级别的 interval 设置可能不生效;
  2. 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
}

该循环的逻辑可概括为三步:

  1. 接收:通过 srv.Recv() 阻塞等待设备推送的 SubscribeResponse;
  2. 溯源:从 gRPC 上下文(peer.FromContext)解析对端地址,分别处理 TCP/UDP/IP 三种地址类型,将来源 IP 作为 source 标记附加到指标上(无法解析时回退为 "unknown");
  3. 处理与回执:调用 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 配置。

登录后查看全文
telegraf