Contributors: Roman Dodin, Matthew MacDonald
Date: March 9, 2024
Version: 0.1.0
The implicit recursive data fetching used by the gNMI servers makes the implementations simple. Whilst the implementation simplicity is important, the lack of server-side filtering for the data requested in gNMI RPCs may be considered a limitation for some gNMI users and systems.
The gNMI Depth Extension allows a client to control the depth of the recursion
when the server evaluates a group of paths in the Subscribe or Get RPC.
Orchestration, Network Management and Monitoring Systems can benefit from this extension as it:
- reduces the load on the server when data is to be fetched from the Network OS during the recursive data extraction
- reduces the bytes on the wire payload, by sending fewer data
gNMI Depth Extension proto specification is defined in [gnmi_ext.proto](https://github.com/openconfig/gnmi/blob/master/proto/gnmi_ext/g nmi_ext.proto).
To explain the concept of the depth-based filtering, consider the following model that is used in the implementation examples throughout this document:
container basket {
leaf name {
type string;
}
leaf-list contents {
type string;
}
list fruits {
key "name";
leaf name {
type string;
}
leaf-list colors {
type string;
}
leaf size {
type string;
}
container origin {
leaf country {
type string;
}
leaf city {
type string;
}
}
}
container description {
leaf fabric {
type string;
}
}
container broken {
presence "This container is broken";
leaf reason {
type string;
}
}
}It's tree representation:
module: app
+--rw basket
+--rw name? string
+--rw contents* string
+--rw fruits* [name]
| +--rw name string
| +--rw colors* string
| +--rw size? string
| +--rw origin
| +--rw country? string
| +--rw city? string
+--rw description
| +--rw fabric? string
+--rw broken!
+--rw reason? string
We populate this data schema with the following values:
basket {
contents [
fruits
vegetables
]
fruits apples {
size XL
colors [
red
yellow
]
origin {
country NL
city Amsterdam
}
}
fruits orange {
size M
}
description {
fabric cotton
}
broken {
reason "too heavy"
}
}
The Depth extension allows clients to specify the depth of the subtree to be returned in the response. The depth is specified as the number of levels below the specified path.
The extension itself has a single field that controls the depth level:
message Depth {
uint32 level = 1;
}Depth value of 0 means no depth limit and behaves the same as if the extension was not specified at all.
Value of 1 means only the specified path and its direct children will be returned. See Children section for more info.
Value of N where N>1 means all elements of the specified path up to N level and direct children of N-th level.
The Depth extension operates the value of "direct children of a schema node". When YANG data modelling language is used, the following elements are considered as children nodes of a schema node:
- leafs
- leaf-lists
In a generic data model language, the children nodes are the elements of scalar type, and arrays of these elements, that are direct descendants of the schema node.
Only these elements are to be returned if depth extension with non-0 value is specified for a specified depth level.
The Depth extension applies to Get and Subscribe requests only. When used with Capability and Set RPC the server should return an error.
Using the data model from Section 2 we will run through a set of examples using the patched version of openconfig/gnmic client with the added Depth extension support.
The most common way to use the depth extension (as we see it) is to use it with level=1. This gets you the immediate child nodes of the schema node targeted by a path.
Consider the following gnmic command targeting /basket path:
gnmic -e json_ietf get --path /basket --depth 1[
{
"contents": [
"fruits",
"vegetables"
]
}
]As per the design, only the leaf and leaf-list nodes are returned. Since our
/basket container has only leaf-list elements (no leafs) a single element
contents is returned.
You can see how this makes it possible to reduce the amount of data extracted by the server and sent over the wire. Many applications might require fetching only leaf values of a certain container to make some informed decision without requiring any of the nested data.
When the path targets the list schema node, all elements of this list is returned with their children nodes
gnmic -e json_ietf get --path /basket/fruits --depth 1[
{
"fruits": [
{
"colors": [
"red",
"yellow"
],
"name": "apples",
"size": "XL"
},
{
"name": "orange",
"size": "M"
}
]
}
]Again, please keep in mind that only leafs and leaf-lists are returned for every list element.
When the depth level is set to values >1, all elements from the path to the provided level value are returned in full with the last level including only leafs and leaf-lists.
gnmic -e json_ietf get --path /basket --depth 2[
{
"broken": {
"reason": "too heavy"
},
"contents": [
"fruits",
"vegetables"
],
"description": {
"fabric": "cotton"
},
"fruits": [
{
"colors": [
"red",
"yellow"
],
"name": "apples",
"size": "XL"
},
{
"name": "orange",
"size": "M"
}
]
}
]Here is what happens:
The 1st level elements are returned, since depth level is 2.
On the 2nd level we return only leafs and leaf-lists, hence the
.fruits.origin is not present.