diff --git a/manageability/mgmt-framework/Telemetry_Subscribe_RPC.md b/manageability/mgmt-framework/Telemetry_Subscribe_RPC.md
index 1712a3cdc466..9ebce22c033e 100644
--- a/manageability/mgmt-framework/Telemetry_Subscribe_RPC.md
+++ b/manageability/mgmt-framework/Telemetry_Subscribe_RPC.md
@@ -13,6 +13,7 @@
- [1.2.4 TARGET_DEFINED subscription](#124-target_defined-subscription)
- [1.2.5 Scalar encoding for telemetry updates](#125-scalar-encoding-for-telemetry-updates)
- [1.2.6 Translib Subscription Infrastructure for DB data](#126-translib-subscription-infrastructure-for-db-data)
+ - [1.2.7 gNOI API to Get Subscribe Preferences](#127-gnoi-api-to-get-subscribe-preferences)
- [1.3 Design Overview](#13-Design-Overview)
- [1.3.1 Basic Approach](#131-Basic-Approach)
- [1.3.2 Container](#132-Container)
@@ -34,6 +35,7 @@
- [3.1.10 ONCE Subscription](#3110-once-subscription)
- [3.1.11 POLL Subscription](#3111-poll-subscription)
- [3.1.12 Wildcard for non-DB Paths](#3112-wildcard-for-non-db-paths)
+ - [3.1.13 Get Subscribe Preferences API](#3113-Get-Subscribe-Preferences-API)
- [3.2 DB Changes](#32-DB-Changes)
- [3.3 Switch State Service Design](#33-Switch-State-Service-Design)
- [3.4 SyncD](#34-SyncD)
@@ -43,6 +45,7 @@
- [3.6.2 CLI](#362-CLI)
- [3.6.3 REST API Support](#363-REST-API-Support)
- [3.6.4 gNMI Support](#364-gNMI-Support)
+ - [3.6.5 gNOI Support](#365-gNOI-Support)
- [3.7 Warm Boot Support](#37-Warm-Boot-Support)
- [3.8 Upgrade and Downgrade Considerations](#38-Upgrade-and-Downgrade-Considerations)
- [3.9 Resource Needs](#39-Resource-Needs)
@@ -56,7 +59,7 @@
- [10.1 Test Cases](#101-test-cases)
- [10.2 UT with Spytest](#102-ut-with-spytest)
- [10.3 UT with gnmi_cli tool](#103-ut-with-gnmi_cli-tool)
- - [10.4 Supported YANG Paths](#104-supported-yang-paths)
+ - [10.4 UT with gnoi_client tool](#104-UT-with-gnoi_client-tool)
- [11 Internal Design Information](#11-Internal-Design-Information)
- [11.1 IS-CLI Compliance](#111-IS-CLI-Compliance)
- [11.2 Broadcom Packaging](#112-Broadcom-SONiC-Packaging)
@@ -80,6 +83,7 @@
| 0.4 | 05/24/2021 | Sachin Holla | Include detailed design and fixes for few comments |
| 0.5 | 06/07/2021 | Sachin Holla | Mention app's role in wildcard path support |
| 0.6 | 08/02/2021 | Sachin Holla | Intro to spytest's gnmi subscribe test tools |
+| 0.7 | 22/02/2022 | Sachin Holla | gNOI API to get subscribe preferences |
# About This Manual
@@ -94,6 +98,8 @@ These paths are supported using the **Translib** library of the
Scope of this document is limited to the infrastructure components only.
HLD for individual features will be documented separately by respective feature teams.
+YANG paths that support subscription are listed in
+[Subscribe YANG Path](https://github.com/BRCM-SONIC/sonic_doc_private/blob/master/manageability/mgmt-framework/Telemetry_Subscribe_Paths.md) guide.
# Definition/Abbreviation
@@ -116,6 +122,10 @@ https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.
gNMI Protobuf Definition
https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto
+Subscribe Supported YANG Paths
+
https://github.com/BRCM-SONIC/sonic_doc_private/blob/master/manageability/mgmt-framework/Telemetry_Subscribe_Paths.md
+
https://github.com/project-arlo/SONiC/blob/master/doc/system-telemetry/telemetry_subscribe_paths.md
+
# 1 Feature Overview
## 1.1 Target Deployment Use Cases
@@ -219,6 +229,28 @@ Translib (and gNMI server) should handle all protocol requirements and DB data m
Apps should be only required to provide yang path to DB mappings and subscription preferences
(whether ON_CHANGE supported, minimum SAMPLE interval, preferred mode for TARGET_DEFINED subscription).
+### 1.2.7 gNOI API to Get Subscribe Preferences
+
+A new gNOI API will be introduced to return subscribe capabilities and preferences of a given path.
+It should accept following inputs:
+
+- One or more subscribe paths (mandatory)
+- A flag to include preferences for all subpaths too (optional)
+- Filter by ON_CHANGE supported/unsupported capability (optional)
+
+Response should be a stream of following data for every path requested.
+
+- Path
+- Whether ON_CHANGE supported
+- Whether ON_CHANGE is the preffred mode.
+ This indicates whether server uses ON_CHANGE or SAMPLE mode for this path when client sends
+ a TARGET_DEFINED subscription request.
+- Whether wildcard keys supported in the subscribe requests
+- Minimum SAMPLE interval allowed.
+
+API should return a gRPC error status if any of the requested paths are invalid;
+or if there was any error while processing the request.
+
## 1.3 Design Overview
### 1.3.1 Basic Approach
@@ -623,6 +655,15 @@ This is individual non-DB data source's implementation specific capability and t
Hence the current design does not support wildcard paths for non-DB data.
Future releases can enhance this based on how non-DB data access evolves in management framework.
+### 3.1.13 Get Subscribe Preferences API
+
+gNOI API details are present in [section 3.6.5](#365-gnoi-support).
+Translib will reuse app module's existing `translateSubscribe` functions to collect requested path's
+DB mappings and subscription preferences similar to TARGET_DEFINED subscription handling.
+Response data for each path (requested path and its subpaths) will be derived from the mapping
+information and streamed out one by one through the channel provided by the gNMI server.
+Response includes a `wildcard_supported` flag, which will be set to true for all db mapped paths.
+
## 3.2 DB Changes
No DB schema change required.
@@ -657,6 +698,43 @@ No REST APIs are added/modified.
No new APIs are added/modified by the infrastructure.
+### 3.6.5 gNOI Support
+
+A new gNOI API **GetSubscribePreferences** will be introduced to return subscribe capabilities
+and preferences for one or more paths.
+This will be defined in a new service `Debug`, in a new protobuf file `sonic_debug.proto`.
+More APIs to get/set server debug information can be added here in future.
+Following is the draft proto file.
+
+```protobuf
+service Debug {
+ // Get subscription capability info for specific paths and their subpaths.
+ rpc GetSubscribePreferences(SubscribePreferencesReq) returns (stream SubscribePreference);
+}
+
+enum Bool {
+ NOTSET = 0;
+ TRUE = 1;
+ FALSE = 2;
+}
+
+// Request message for GetSubscribePreferences RPC
+message SubscribePreferencesReq {
+ repeated string path = 1; // Yang paths as gNMI path strings
+ bool include_subpaths = 2; // Get preferences for all subpaths also
+ Bool on_change_supported = 3; // Filter by on_change supported/unsupported
+}
+
+// SubscribePreference holds subscription preference information for a path.
+message SubscribePreference {
+ string path = 1; // A yang path, in gNMI path string syntax
+ bool on_change_supported = 2; // Whether on_change supported
+ bool on_change_preferred = 3; // Whether target_defined maps to on_change
+ bool wildcard_supported = 4; // Whether wildcard keys supported
+ uint64 min_sample_interval = 5; // Minimum sample interval, in nanoseconds
+}
+```
+
## 3.7 Warm Boot Support
N/A
@@ -795,6 +873,21 @@ ONCE subscription test cases:
- ONCE subscription for a non-DB path, without wildcard keys
- ONCE subscription with unknown path
+GetSubscribePreferences gNOI API:
+
+- Get preferences for a container path that supports ON_CHANGE and all its subpaths also support ON_CHANGE
+- Get preferences for a container path that supports ON_CHANGE but some of its child paths do not
+- Get preferences for a path that do not support ON_CHANGE
+- Get preferences for a leaf path (with and without ON_CHANGE support)
+- Get preferences for multiple paths
+- Get preferences with include_subpaths=true
+- Get preferences with on_change_supported filter (both TRUE and FALSE)
+- Get preferences for a non-db path
+- Get preferences without wildcard keys and without module prefixes
+- Check error response for an invalid path
+- Send request and close the client stream immediately (manual verification of server logs)
+- Send request and close the channel immediately (manual verification of server logs)
+
## 10.2 UT with Spytest
Spytest module `apis.yang.utils.gnmi` provides APIs to connect, subscribe and verify notifications.
@@ -907,9 +1000,49 @@ gnmi_cli -insecure -logtostderr -target OC_YANG -address localhost:8080 \
-query openconfig-interfaces:interfaces/interface[name=*]/config,openconfig-acl:acl/acl-sets
```
-## 10.4 Supported YANG Paths
+## 10.4 UT with gnoi_client tool
+
+gnoi_client tool can be used for quick verification of the gNOI APIs supported by the telemetry server.
+It will be available in the **telemetry** container.
+It can also be obtained from the build server `sonic-buildimage/src/sonic-telemetry/build/bin` directory.
+
+Following are the few examples of GetSubscribePreferences API calls.
+
+1\) Get preferences for one or more paths
-Please refer to [Subscribe YANG Path](https://github.com/BRCM-SONIC/sonic_doc_private/blob/master/manageability/mgmt-framework/Telemetry_Subscribe_Paths.md) guide.
+```
+gnoi_client -username admin -password YourPaSsWoRd -insecure \
+ -module Debug -rpc GetSubscribePrefs \
+ /openconfig-interfaces:interfaces/interface[name=*]/state
+
+gnoi_client -username admin -password YourPaSsWoRd -insecure \
+ -module Debug -rpc GetSubscribePrefs \
+ /openconfig-interfaces:interfaces/interface[name=*]/state /openconfig-acl:acl
+```
+
+2\) Get preferences for subpaths also (use subpaths=true option)
+
+```
+gnoi_client -username admin -password YourPaSsWoRd -insecure \
+ -module Debug -rpc GetSubscribePrefs \
+ /openconfig-interfaces:interfaces/interface/state subpaths=true
+```
+
+3\) Get preferences for ON_CHANGE supported/not supported paths only (use onchange=true/false option)
+
+```
+gnoi_client -username admin -password YourPaSsWoRd -insecure \
+ -module Debug -rpc GetSubscribePrefs \
+ /openconfig-interfaces:interfaces/interface/state subpaths=true onchange=true
+```
+
+Use --help option to view the usage info and suppported -module and -rpc values.
+
+```
+gnoi_client --help /* list all module and all rpc values */
+gnoi_client -module System --help /* list all rpcs of 'System' module */
+gnoi_client -rpc Get* --help /* list all rpcs matching a glob pattern */
+```
# 11 Internal Design Information