Merge pull request sonic-net#325 from sachinholla/subscribe_prefs_gnoi

gNOI API to get subscribe preferences
sg893052 · Feb 28, 2022 · 1d8de92 · 1d8de92
2 parents b8a2fc6 + 16c6a36
commit 1d8de92
Showing 1 changed file with 136 additions and 3 deletions.
diff --git 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<br>
 https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto
 
+Subscribe Supported YANG Paths
+<br>https://github.com/BRCM-SONIC/sonic_doc_private/blob/master/manageability/mgmt-framework/Telemetry_Subscribe_Paths.md
+<br>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