gnmic-subscribe

Subscribe to target state updates under the subtree of a specific path

$ gnmic [[-a|--address]] [ip:port] subscribe --path [path]

$ gnmic [[-a|--address]] [ip:port] subscribe --path [path] --sample-interval 30s

$ gnmic [[-a|--address]] [ip:port] subscribe --path [path] --stream-mode on-change --heartbeat-interval [1m]

$ gnmic [[-a|--address]] [ip:port] subscribe --path [path] --mode once

$ gnmic [[-a|--address]] [ip:port] subscribe --path [path] [[-e|--encoding]] json_ietf

gnmic subscribe [options] [paths...]

Examples:
gnmic subscribe --target router1:50051 --path /interfaces/interface/state/oper-status --mode stream --stream-mode on-change
gnmic subscribe --target router2:50051 --path /system/cpu --mode poll --interval 10s
gnmic subscribe --target router3:50051 --path / --mode once

--mode mode
    Specifies the subscription mode. Common modes include ONCE (single snapshot), POLL (periodic snapshots), and STREAM (continuous updates).

--stream-mode mode
    Defines the streaming mode for STREAM subscriptions. Options are ON_CHANGE (updates only when data changes) or SAMPLE (updates at a specified interval).

--path path
    One or more gNMI paths to subscribe to. Can be specified multiple times for different paths.

--target target
    The gNMI target (device address:port) to connect to. Can be specified multiple times for subscribing to multiple targets concurrently.

--model name
    Specifies the OpenConfig or custom YANG model(s) to be used for the subscription. Can be specified multiple times.

--interval duration
    Sets the sampling interval for POLL or STREAM (SAMPLE sub-mode) subscriptions (e.g., '10s', '5m').

--encoding encoding
    The desired encoding for the received data. Common values include JSON, JSON_IETF, PROTO, ASCII, BYTES.

--output format
    Determines the format of the output messages. Examples: json, event, flat, proto.

--tls-ca file
    Path to the CA certificate file for TLS authentication.

--tls-cert file
    Path to the client certificate file for TLS authentication.

--tls-key file
    Path to the client private key file for TLS authentication.

--tls-skip-verify
    Skips TLS certificate and host verification (use with caution).

The gnmic-subscribe command is a core function of the gnmic gNMI client, designed to initiate and manage gNMI subscription streams. It allows users to receive real-time updates from network devices conforming to the gNMI (gRPC Network Management Interface) specification. Unlike one-off get requests, subscriptions provide continuous data delivery based on specified paths and modes. This command supports various subscription modes, including ONCE (a single snapshot), POLL (periodic snapshots), and STREAM (continuous updates). For STREAM mode, further sub-modes like ON_CHANGE (updates only when data changes) and SAMPLE (updates at regular intervals) are available. It's crucial for monitoring network state, collecting telemetry, and integrating with data analytics platforms. Users can specify target devices, data paths, desired encoding, and output formats, making it a versatile tool for network observability.

Long-running subscriptions can consume significant network bandwidth and device resources, especially with frequent updates or large data sets. Ensure network stability and device capacity to avoid connection drops or performance degradation. Misconfigured paths or models may lead to no data being received or errors. Security considerations, such as proper TLS setup, are paramount when connecting to production devices.

ONCE: Fetches the current state of the subscribed paths once, then terminates.
POLL: Periodically fetches the current state of the subscribed paths at a specified interval.
STREAM: Maintains an open connection and continuously streams updates. This mode has further sub-modes:

ON_CHANGE: Sends updates only when the value of a subscribed path changes.
SAMPLE: Sends updates at a regular, specified interval, regardless of whether the data has changed. Often used for performance metrics.
TARGET_DEFINED: The target device decides how to send updates for a path, typically a mix of ON_CHANGE and SAMPLE behavior.

gNMI paths identify specific data nodes within a device's YANG data model. They can be absolute (starting with '/') or relative. Wildcards ('*') are often supported by devices for subscribing to multiple elements or sub-trees.

gnmic itself is a relatively modern tool, developed to provide a robust and easy-to-use command-line interface for the gNMI protocol. The subscribe command has been a fundamental part of gnmic since its early versions, reflecting gNMI's primary use case for streaming telemetry and real-time network monitoring. Its evolution has focused on improving stability, expanding supported gNMI features (like history, qos), and enhancing usability with various output formats and connection options.

gnmic-get(1), gnmic-set(1), gnmic-capabilities(1), gnmic-diff(1)