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.
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". What we understand by direct children:
- leafs
- leaf-lists
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. We can provide the patched gnmic binary for Linux x86_84 if you want to try it out.
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.
Netconf standardized max-depth in RFC 85226:
The "max-depth" parameter can be used by the client to limit the number of subtree levels that are returned in the reply.
The NETCONF way of using the max-depth differs in a sense that depth=1 returns the element pointed by the path, but not its children. depth=2 returns children of the element pointed by the path.
I find this behavior strange, as I don't see an operational reason to return the element itself when depth is 1.
We believe that the Depth extension has a generic applicability whilst not bein a burden for the implementation (henceforth no subtree filtering with XPath or anything of sorts).
Yet it delivers important quality of life improvements for consuming systems that may get the required data nodes faster and with less processing time spent.
This is assuming that cumulative time of fetching only leaf/leaf-lists values by the server is smaller than the recursive data retrieval combined with payload unmarshalling on the client side.