Skip to content

Subscribe

Description#

The [subscribe | sub] command represents the gNMI Subscribe RPC.

It is used to send a Subscribe Request to the specified target(s) and expects one or multiple Subscribe Response

Usage#

gnmic [global-flags] subscribe [local-flags]

Local Flags#

The subscribe command supports the following local flags:

prefix#

The [--prefix] flag sets a common prefix to all paths specified using the local --path flag. Defaults to "".

path#

The path flag [--path] is used to specify the path(s) to which the client wants to subscribe.

Multiple paths can be specified, either as a comma separated string:

gnmic subscribe --path "/state/ports[port-id=*],\
                       /state/router[router-name=*]/interface[interface-name=*]"

Or using repeated --path flags:

gnmic sub --path "/state/ports[port-id=*]" \
          --path "/state/router[router-name=*]/interface[interface-name=*]"

If a user needs to provide origin information to the Path message, the following pattern should be used for the path string: "origin:path":

gnmic sub --path "openconfig-interfaces:interfaces/interface"

target#

With the optional [--target] flag it is possible to supply the path target information in the prefix field of the SubscriptionList message.

model#

The [--model] flag is used to specify the schema definition modules that the target should use when extracting the data to stream back.

qos#

The [--qos] flag specifies the packet marking that is to be used for the responses to the subscription request.

mode#

The [--mode] mode flag specifies the mode of subscription to be created.

This may be one of: ONCE, STREAM or POLL.

It is case insensitive and defaults to STREAM.

stream subscription mode#

The [--stream-mode] flag is used to specify the stream subscription mode.

This may be one of: ON_CHANGE, SAMPLE or TARGET_DEFINED

This flag applies only if --mode is set to STREAM. It is case insensitive and defaults to SAMPLE.

sample interval#

The [--sample-interval] flag is used to specify the sample interval to be used by the target to send samples to the client.

This flag applies only in case --mode is set to STREAM and --stream-mode is set to SAMPLE.

Valid formats: 1s, 1m30s, 1h. Defaults to 0s which is the lowest interval supported by a target.

heartbeat interval#

The [--heartbeat-interval] flag is used to specify the server heartbeat interval.

The heartbeat interval value can be specified along with ON_CHANGE or SAMPLE stream subscriptions modes.

  • ON_CHANGE: The value of the data item(s) MUST be re-sent once per heartbeat interval regardless of whether the value has changed or not.
  • SAMPLE: The target MUST generate one telemetry update per heartbeat interval, regardless of whether the --suppress-redundant flag is set to true.

quiet#

With [--quiet] flag set gnmic will not output subscription responses to stdout. The --quiet flag is useful when gnmic exports the received data to one of the export providers.

suppress redundant#

When the [--suppress-redundant] flag is set to true, the target SHOULD NOT generate a telemetry update message unless the value of the path being reported on has changed since the last update was generated.

This flag applies only in case --mode is set to STREAM and --stream-mode is set to SAMPLE.

updates only#

When the [--updates-only] flag is set to true, the target MUST not transmit the current state of the paths that the client has subscribed to, but rather should send only updates to them.

name#

The [--name] flag is used to trigger one or multiple subscriptions already defined in the configuration file see defining subscriptions

Examples#

1. streaming, target-defined, 10s interval#

gnmic -a <ip:port> sub --path /state/port[port-id=*]/statistics

2. streaming, sample, 30s interval#

gnmic -a <ip:port> sub --path "/state/port[port-id=*]/statistics" \
                       --sample-interval 30s

3. streaming, on-change, heartbeat interval 1min#

gnmic -a <ip:port> sub --path "/state/port[port-id=*]/statistics" \
                       --stream-mode on-change \
                       --heartbeat-interval 1m

4. once subscription#

gnmic -a <ip:port> sub --path "/state/port[port-id=*]/statistics" \
                       --mode once