The subscribe RPC is part of the telemetry support in gNMI.
A subscription is initiated from the gRPC client by sending a Subscribe RPC that contains a "SubscribeRequest" message to the gRPC server. A prefix can be specified to be used with all paths specified in the "SubscribeRequest". If a prefix is present, it is appended to the start of every path to provide a full path.
A subscription contains:
a list of one or more paths. The following conditions apply:
A path represents the data tree as a series of repeated strings and elements. Each element represents a data tree node name and its associated attributes.
A path must be syntactically valid within the set of schema modules that the gRPC server supports.
The path list cannot be modified during the lifetime of the subscription.
If the subscription path is to a container node, all child leafs of that container node are considered to be subscribed to.
Any specified path must be unique within the list; paths cannot be repeated within the list. An error is returned if the same path is used more than one time in a single subscription.
A specified path does not need to pre-exist within the current data tree on the gRPC server. If a path does not exist, the gRPC server continues to monitor for the existence of the path. Assuming that the path exists, the gRPC server transmits telemetry updates.
The gRPC server does not send any data for a non-existent path; for example, if a path is non-existent at the time of subscription creation or if the path was deleted after the subscription was established.
The maximum number of paths for all subscriptions on a single SR OS device is 14400. A path using a wildcard is still considered a single path.
a subscription mode of one of the following types:
ONCE mode
The server returns only one notification containing all information the client has subscribed to. In general, retrieving large amounts of information from the NE can be done using telemetry: ‟SubscribeRequest” message with ONCE subscription type.
ON_CHANGE mode
The server returns notifications only when the value of the subscribed field changes. See ON_CHANGE subscription mode for more information.
SAMPLE mode
The gRPC server sends notifications at the specified sampling interval.
TARGET_DEFINED mode
This refers to ON_CHANGE for all states supporting ON_CHANGE notifications and SAMPLE mode for all other objects in the YANG tree.
a sample interval is supported for each path. If a sample interval of less than 1 s is specified, the gRPC server returns an error. If the sample interval is set to 0, the default value of 10 s is used. A sample interval is specified in nanoseconds (10 000 000 000 by default)
When a subscription is successfully initiated on the gRPC server, ‟SubscribeReponse” messages are sent from the gRPC server to the gRPC client. The ‟SubscribeResponse” message contains update notifications about the subscription's path list.
An update notification contains:
a timestamp of the statistics collection time, represented in nanoseconds
a prefix
If a prefix is present, it is logically appended to the start of every path to provide the full path.
The presence of a prefix in the ‟SubscribeResponse” message is not related to the presence of a prefix in the original ‟SubscribeRequest” message. The prefix in the ‟SubscribeResponse” message is optimized by the gRPC server.
a list of updates (path and value pairs)
A path represents the data tree path as a series of repeated strings or elements, where each element represents a data tree node name and its associated attributes. See Schema paths for more information.
The ‟TypedValue” message represents the value of the data tree node, where the encoding is ‟JSON”, ‟JSON_IETF”, ‟Bytes”, or ‟Protobuf” depending on the information in the ‟SubscribeRequest” message.
Multiple notification messages can be combined in a single ‟SubscribeResponse” message. This bundling minimizes overhead, which improves the efficiency of telemetry data transport, however, this may delay some notifications and timestamps may be less accurate. The following parameters control message bundling:
A sync response notification is sent one time after the gRPC server sends all updates for the subscribed-to paths. The sync response must be set to ‟true” for the gRPC client to consider that the stream has synced one time. A sync response is used to signal the gRPC client that it has a full view of the subscribed-to data.
The gRPC server sends an error, if required. The error contains a description of the problem.
Authorization checks are not performed by default for telemetry data. All configuration and state elements are available to authenticated telemetry subscriptions, with the exception of LI (Lawful Intercept) configuration and state elements, which are authorized separately based on the LI authorization configuration. To control telemetry data authorization, use the classic CLI configure>system>security>managment-interface>output-authorization> telemetry-data command or the MD-CLI configure system security aaa management-interface output-authorization telemetry-data command.