gNMI

gNMI (gRPC Network Management Interface) is a streaming telemetry protocol defined by OpenConfig. The device pushes data to Prelude Collector over a persistent gRPC connection, replacing the polling model of SNMP with low-latency, push-based updates. After the first mention, this page refers to Prelude Collector as "the collector".

The collector subscribes once per Model in STREAM mode with the SAMPLE subscription type, and the device streams updates at the configured sample interval. Updates are encoded as JSON_IETF.

When to use

Pick gNMI when the device supports it and the data you need lives in its YANG tree. It is the right answer for almost all modern routers and switches — Cisco IOS-XR, IOS-XE 17+, NX-OS 9+, Juniper Junos, Arista EOS, and Nokia SR OS all expose first-class gNMI today. Use it whenever you need sub-second to seconds-grade freshness or when you want one TCP session per device to carry many subscriptions.

Connection settings

A gNMI Protocol record carries the device-side transport settings:

The collector-wide gNMI tuning values apply to every gNMI Protocol record and are set via COLLECTOR_GNMI_* environment variables. See the Configuration reference for the full list:

For the exact field list and types accepted by the API, see the API reference for Protocols.

Authentication options

Username / password over TLS

The default. The collector opens a TLS gRPC connection to the device and attaches username and password as gRPC metadata on every RPC. This is what you get with the example below.

Plaintext username / password

For lab use only. Set tls: false on the Protocol record. The same credentials are injected as metadata, but the channel is unencrypted. Do not use this against devices reachable from anything wider than a management VLAN.

Self-signed certificates

When the device presents a self-signed certificate, set tls: true and insecure: true. The TLS handshake completes but certificate validation is skipped. Plan to replace this with a properly signed certificate before production.

Examples

Device + Protocol record

Create a Device and attach a gNMI Protocol against an Arista EOS box:

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X POST "$BASE/api/v1/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "core-router-01",
    "ip": "192.0.2.10",
    "active": true
  }'

curl -s -X POST "$BASE/api/v1/protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "type": "gnmi",
    "address": "192.0.2.10:6030",
    "username": "admin",
    "password": "<your-device-password>",
    "tls": true,
    "insecure": true
  }'

Bruno: 02 Devices / Create device, 03 Protocols / Create gNMI protocol

Subscription to interface counters

Once the Protocol is attached, bind it to a built-in Model with a Subscription:

device_id: 1
model: interfaces
interval: 30
enabled: true

For gNMI, interval is interpreted as the requested sample interval in seconds and is sent to the device as the SAMPLE interval on the subscription. Use coarse values (10 seconds or longer) for production fleets to avoid pressuring device telemetry stacks.

Limitations

• Vendor coverage of YANG paths is uneven. If the metric you need is not exposed in the device's YANG tree, gNMI cannot fish it out. Fall back to NETCONF or SNMP for that one Field.
• Streaming subscriptions are sticky. A flapping management link causes a reconnect storm; tune subscription-stagger-delay and max-concurrent-subscriptions if your devices struggle when many subscriptions start at once.
• Certificate verification is skipped when insecure: true is set. Use this for self-signed lab certificates only.
• Subscriptions always use STREAM mode with SAMPLE updates. ON_CHANGE and ONCE are not exposed by the collector — SAMPLE was chosen for predictable, rate-limited delivery.

Troubleshooting

Test Connection from the device UI

Open the device's Protocols tab in the web UI and click Test Connection on the gNMI Protocol row. The collector runs a Capabilities exchange against the device using the credentials stored on the Protocol record and reports success, failure, or the exact error returned by the device. Use this first whenever a subscription stops producing Snapshots — a green Test Connection proves auth and TLS are healthy and narrows the problem to the subscription paths.

gnmic-like one-shot path test

For raw path probing without creating a Model, the collector exposes a gnmic-style endpoint that runs a one-shot collection against an existing Device and returns the raw updates the device sends back:

curl -s -X POST "$BASE/api/v1/protocols/test-path" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device-id": 1,
    "protocol": "gnmi",
    "paths": ["/interfaces/interface/state/counters"]
  }'

Bruno: 03 Protocols / Test path (gNMI)

The response contains the resolved YANG paths, raw DataUpdate records, and any errors emitted by the gNMI client. Use it to confirm a path actually returns data on the target platform before wiring it into a Model and Mapping.

Common errors

Connection refused — verify the gNMI port is open from the collector host:

nc -zv 192.0.2.10 6030

TLS handshake errors — TLS is enabled on the Protocol record but the device expects plaintext, or vice versa. Match the tls setting to whatever grpc tls / grpc no-tls knob the device exposes.

Capabilities exchange succeeds but subscriptions fail — the device may reject subscriptions for unsupported YANG paths. The error returned by the device is forwarded into the Snapshot's error field; fetch the Snapshot to read it. The test-path endpoint above is the fastest way to isolate which path is the offender.

See also

• Collection protocols
• Choosing a protocol
• Configuration: gNMI
• First Collection
• API: Protocols