Sổ tay kỹ thuật

gNMI, YANG và cú pháp path

concept#gnmi#yang#openconfig#telemetry· cập nhật 2026-11-06

Dùng khi cần hiểu 4 RPC của gNMI, chọn giữa model OpenConfig và native, viết đúng path và chọn encoding trước khi dùng gnmic hay Telegraf.

Sửa trang này
Mục lục

gNMI (gRPC Network Management Interface) là giao thức của OpenConfig để đọc, ghi cấu hình và stream telemetry qua gRPC (HTTP/2, thường có TLS). Dữ liệu được mô tả bằng YANG model, và mỗi giá trị được định vị bằng một path dẫn theo cây YANG đó.

Luồng RPC

sequenceDiagram
  participant C as Client (gnmic, Telegraf)
  participant R as Router (gNMI server)
  C->>R: CapabilitiesRequest
  R-->>C: models + encodings hỗ trợ
  C->>R: GetRequest(path, type, encoding)
  R-->>C: GetResponse(notification)
  C->>R: SetRequest(update, replace, delete)
  R-->>C: SetResponse (áp dụng nguyên tử)
  C->>R: SubscribeRequest(STREAM, SAMPLE 10s)
  R-->>C: Notification ... (liên tục)
  R-->>C: sync_response

Bốn RPC

RPC Mục đích Ghi chú
Capabilities Liệt kê model YANG (tên, org, version), encoding, phiên bản gNMI Luôn chạy đầu tiên để biết thiết bị hỗ trợ gì
Get Lấy snapshot type: ALL, CONFIG, STATE, OPERATIONAL
Set Ghi cấu hình Một request gồm nhiều delete / replace / update, thiết bị áp dụng tất cả hoặc không gì cả
Subscribe Telemetry Mode STREAM, ONCE, POLL

Subscribe mode

Mode Hành vi Dùng khi
STREAM + SAMPLE Gửi đều theo sample_interval Counter interface, CPU, memory
STREAM + ON_CHANGE Gửi khi giá trị thay đổi Trạng thái oper-status, BGP session state
STREAM + TARGET_DEFINED Thiết bị tự chọn sample hay on-change theo từng leaf Không chắc leaf nào hỗ trợ on-change
ONCE Gửi một lần rồi kết thúc Thay cho Get trên thiết bị chỉ hỗ trợ Subscribe
POLL Client gửi poll thì thiết bị mới trả Ít dùng

Update, replace, delete trong Set

Thao tác Ý nghĩa
update Merge giá trị vào path, giữ phần còn lại
replace Thay toàn bộ cây con tại path (phần không khai báo bị xoá hoặc về mặc định)
delete Xoá path

YANG: OpenConfig hay native

OpenConfig Native (vendor)
Ví dụ module openconfig-interfaces, openconfig-network-instance, openconfig-bgp IOS XR: Cisco-IOS-XR-infra-statsd-oper, Cisco-IOS-XR-um-*-cfg. Junos: path theo cây CLI /interfaces/interface/..., /junos/system/...
Đa vendor Cùng path cho IOS XR, Junos, EOS... Mỗi vendor mỗi kiểu
Độ phủ Thiếu một số tính năng riêng Phủ gần đủ tính năng
Ổn định Có thể khác version giữa các OS release (deviation) Bám theo OS release
Nên dùng Dashboard/alert dùng chung nhiều vendor Tính năng không có trong OpenConfig, counter chi tiết

Model nào được hỗ trợ và deviation của từng release: IOS XR xem repo YangModels/yang thư mục vendor/cisco/xr/<release>. Junos xem Juniper YANG Data Model Explorer. Nhanh nhất vẫn là gnmic capabilities trên chính thiết bị.

Cú pháp path

Path gNMI là chuỗi các phần tử, mỗi phần tử có thể có key trong []:

/interfaces/interface[name=GigabitEthernet0/0/0/1]/state/counters/in-octets
/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=default]/bgp/neighbors/neighbor[neighbor-address=192.0.2.2]/state
Thành phần Cú pháp Ví dụ
Phần tử /elem /interfaces/interface
Key [key=value], nhiều key viết liên tiếp [identifier=BGP][name=default]
Wildcard key [key=*] /interfaces/interface[name=*]/state/oper-status
Wildcard phần tử * /interfaces/interface/*/counters (tuỳ thiết bị hỗ trợ)
Origin origin:path hoặc trường origin riêng openconfig:/interfaces, Cisco-IOS-XR-infra-statsd-oper:infra-statistics
Prefix Phần chung tách riêng khỏi path prefix /interfaces/interface[name=Gi0/0/0/1], path state/counters

Tên interface có / vẫn để nguyên trong [] vì nằm trong key. Khi gõ trên shell, bọc path trong nháy đơn để [ ] * không bị shell xử lý.

Path IOS XR native thường bắt đầu bằng <module>:<container>, ví dụ:

Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/latest/generic-counters
Cisco-IOS-XR-wdsysmon-fd-oper:system-monitoring/cpu-utilization

Encoding

Encoding Mô tả Ghi chú
JSON JSON thường
JSON_IETF JSON theo RFC 7951 (có tiền tố module ở key khi đổi namespace) Phổ biến cho Get/Set trên IOS XR
PROTO Giá trị scalar dạng protobuf TypedValue Gọn nhất cho Subscribe tần suất cao
BYTES, ASCII Ít dùng

Encoding nào được hỗ trợ khác nhau theo vendor và release: kiểm tra trường supported_encodings trong Capabilities, đừng đoán.

Khi nào dùng

  • gNMI Subscribe thay SNMP polling cho counter tần suất cao (10s trở xuống) và trạng thái on-change. Xem Telegraf gNMI input và Model-driven telemetry IOS XR.
  • gNMI Set khi muốn đẩy config có cấu trúc, nguyên tử, cùng model với telemetry. Nếu thiết bị hay quy trình đã chuẩn hoá NETCONF (candidate, commit confirmed), dùng NETCONF với ncclient.
  • CLI/SSH vẫn hợp cho lệnh show một lần hoặc thiết bị cũ không có gNMI.

Lệnh thực tế: gnmic cheatsheet.

Tham khảo