gNMI 快速入门:如何用 gNMI(gRPC 网络管理接口)采集网络设备流式遥测数据
gNMI 快速入门:如何用 gNMI(gRPC 网络管理接口)采集网络设备流式遥测数据
gNMI(gRPC Network Management Interface) 是 OpenConfig 推出的网络管理接口标准,基于 gRPC 协议实现设备数据的订阅与流式遥测(streaming telemetry)采集。本仓库提供了 gNMI 的参考 Go 实现:gNMI 客户端库、命令行工具 gnmi_cli,以及可连接多台设备并集中缓存遥测数据的 gnmi_collector 收集器。本文将带你快速上手 gNMI,从安装、第一次查询到搭建流式遥测收集器。
一、什么是 gNMI?核心概念 3 分钟看懂
gNMI 在 proto/gnmi/gnmi.proto 中定义了 4 个核心 RPC 方法,覆盖了网络遥测与管理的基本需求:
| RPC 方法 | 功能 | 说明 |
|---|---|---|
Capabilities |
能力查询 | 查询设备支持的服务版本和 YANG 模型 |
Get |
快照获取 | 一次性获取数据树的快照 |
Set |
数据修改 | 更新设备上的配置/状态数据 |
Subscribe |
订阅流式数据 | 客户端按需订阅路径值,支持流式推送 ⭐ |
对于"流式遥测"场景,最核心的就是 Subscribe 方法。它支持 3 种查询类型(见 client/query.go):
- Once(单次查询):返回一次初始快照后结束;
- Polling(轮询):按固定间隔(默认 30 秒)重复获取数据;
- Streaming(流式订阅):长期保持连接,设备侧有更新即推送,是遥测场景的默认选择。
💡 简单记忆:查配置用 Once,定时巡检用 Polling,实时大盘用 Streaming。
二、仓库结构:三大组件一览
本仓库包含 3 个可直接使用的组件,目录结构清晰,按需取用:
| 组件 | 路径 | 用途 |
|---|---|---|
| gNMI 客户端库 | client/ | Go 库形式接入 gNMI,适合二次开发 |
| gNMI CLI | cmd/gnmi_cli/ | 命令行查询工具,调试首选 |
| gNMI 收集器 | cmd/gnmi_collector/ | 缓存型收集器,连接多台设备后通过单个 gNMI 订阅接口对外提供数据 |
辅助模块还包括:基于树的缓存 cache/(配合 ctree/ 使用)、路径匹配 match/、订阅会话管理 subscribe/,以及用于测试的模拟 gNMI 目标 testing/fake/gnmi/。
三、安装步骤:一条命令获取 gNMI 工具
方式 1:直接安装 CLI(推荐新手)
go get -u github.com/openconfig/gnmi/cmd/gnmi_cli
方式 2:克隆仓库本地构建
git clone https://gitcode.com/gh_mirrors/gn/gnmi
cd gnmi
go build ./cmd/gnmi_cli
项目基于 Go 1.22(见 go.mod),依赖 google.golang.org/grpc 和 google.golang.org/protobuf,环境装好 Go 后即可编译。
四、第一次查询:5 分钟验证 gNMI 连接
启动一个模拟 gNMI 目标(Target)
没有真实设备也能练手!仓库自带 fake gNMI server,说明见 testing/fake/gnmi/cmd/fake_server/README.md:
fake_server --config config.pb.txt --port 8080 \
--server_crt <服务器证书> --server_key <服务器私钥> \
--allow_no_client_auth --logtostderr
使用 gnmi_cli 发起查询
启动后,用一行命令验证连接(* 表示订阅所有路径):
gnmi_cli -a localhost:8080 -q '*' -insecure -qt s
参数含义:-a 指定目标地址,-q 指定查询路径(支持 glob 通配),-qt s 表示 streaming 查询类型。
常用参数速查表
| 参数 | 缩写 | 作用 |
|---|---|---|
--address |
-a |
gNMI 目标地址(IP:端口) |
--query |
-q |
查询路径,可用 * 通配 |
--query_type |
-qt |
查询类型:o(once) / p(polling) / s(streaming) |
--polling_interval |
-pi |
轮询间隔,默认 30s |
--count |
-c |
事件数量上限,0 为无限 |
--display_type |
-dt |
输出格式:group / single / proto |
--streaming_duration |
-sd |
流式采集持续时间 |
--updates_only |
-u |
仅推送更新,跳过初始同步 |
完整参数定义见 cmd/gnmi_cli/gnmi_cli.go。
🔐 真实设备通常需要 TLS 证书与账号密码:--with_user_pass 可交互式输入凭据,--ca_crt 用于校验服务端证书。
五、流式遥测收集:gnmi_collector 实战
当设备规模扩大(几十上百台),逐台订阅不现实。gnmi_collector 作为缓存型收集器,持续从多台目标拉取遥测数据,写入带时间戳的树形缓存,再通过一个 gNMI 订阅接口统一对外提供——相当于遥测数据的"中央汇聚点" 🎯
编写收集器配置
配置文件为 textproto 格式,定义"订阅什么请求"和"连接哪些目标"。参考示例 cmd/gnmi_collector/testdata/good.cfg:
request: <
key: "interfaces"
value: <
subscribe: <
prefix: < origin: "openconfig" >
subscription: <
path: < elem: < name: "interfaces" > >
>
>
>
>
target: <
key: "target1"
value: <
addresses: "127.0.0.1:9998"
request: "interfaces"
credentials: <
username: "username"
password: "password"
>
>
>
配置分两部分:request 描述要订阅的 gNMI 请求(如 interfaces 路径),target 描述设备地址与凭据。若设备需主动反向连接,可使用隧道模式(addresses: "use_tunnel:0",示例见 cmd/gnmi_collector/testdata/good_tunnel.cfg)。
启动收集器
gnmi_collector \
--config_file example.cfg \
--cert_file cert.pem \
--key_file key.pem \
--port 8888
启动后收集器监听 8888 端口,客户端即可用 gnmi_cli -a localhost:8888 查询汇聚后的数据。核心运行逻辑见 cmd/gnmi_collector/gnmi_collector.go。
容器化部署也很方便,参考 cmd/gnmi_collector/docker/README.md 和其中的 Dockerfile。
💡 生产提示:示例目录 config/ 中的 cert.pem、key.pem 仅供测试,正式环境请重新生成证书。
六、进阶:读懂遥测数据的缓存机制
收集器"缓存 + 订阅"的设计值得了解:
- 树形缓存:cache/cache.go 中每个 target 维护一棵 ctree/ 数据树,所有更新带纳秒级时间戳,过旧(stale)或超前(future)的更新会被拒绝,保证数据一致性;
- 路径匹配:客户端订阅时,match/ 模块判断请求路径与缓存中哪些叶子节点匹配;
- 合并更新:coalesce/ 模块将高频变化合并,避免数据洪峰;
- 自动重连:连接断开后 client/reconnect.go 按退避策略自动重连,配合 collector/ 提供的
ReconnectgRPC 接口可手动强制重连。
这套机制让收集器既能吸收"千台设备的实时推送",又能平滑地"喂给"下游分析系统。
七、常见问题 FAQ
Q1:gNMI 和 SNMP 有什么区别? SNMP 是轮询式、能力有限;gNMI 基于 gRPC 流式推送,延迟更低、可扩展性更好,是现代流式遥测的事实标准。
Q2:如何确认设备支持哪些能力?
使用 gnmi_cli -capabilities -address <地址> 查询设备的服务版本与 YANG 模型列表。
Q3:想在自己的 Go 程序中集成 gNMI 怎么办?
直接导入客户端库,主入口在 client/client.go,通过 Query 结构体描述目标地址、路径与查询类型即可。
Q4:如何调试收集器配置问题?
仓库提供测试配置 cmd/gnmi_collector/testdata/(含 bad.cfg、unparseable.cfg 等),可对照排查格式与解析错误。
八、总结
本文带你完成了 gNMI 流式遥测数据采集的快速入门:
- ✅ 理解 gNMI 四大 RPC 与 3 种查询类型(Once / Polling / Streaming);
- ✅ 安装
gnmi_cli并用 fake server 完成第一次订阅查询; - ✅ 用
gnmi_collector搭建多设备遥测汇聚的缓存收集器。
gNMI 是构建现代网络遥测系统的第一块积木。建议下一步深入 proto/gnmi/ 中的协议定义,以及 client/ 客户端库的完整 API,动手搭建属于你自己的遥测流水线 🚀