Skip to content

gNMI: Add section to cover atomic datasets #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
earies wants to merge 1 commit into
base: master
Choose a base branch
from
Open

gNMI: Add section to cover atomic datasets #229

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions rpc/gnmi/gnmi-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
Paul Borman, Marcus Hines, Carl Lebsack, Chris Morrow, Anees Shaikh, Rob Shakir, Wen Bo Li, Darren Loher

**Date:**
May 25, 2023
Oct 1, 2025

**Version:**
0.10.0
0.11.0

**[gNMI service](https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto) compatibility:**
0.10.x
Expand Down Expand Up @@ -1680,6 +1680,44 @@ of the values, retaining a consistent sample period and having a robust
mechanism to ensure that sampling artifacts are not introduced (e.g. a constant
rate byte flow over an interface appearing to have adjacent spikes and dips).

##### 3.5.2.1.1 Atomic Datasets

When multiple datapoints (e.g. Update messages) are bundled within a single
Notification message and the intent is that the dataset must be delivered as a
single PDU (e.g. in order to make sense of relational data), the `atomic` field
in the Notification message structure MUST be set to `true` and all datapoints
will share the same Notification timestamp.

If the data content is modeled in the YANG language, a YANG extension SHOULD be
annotated on a corresponding structure to be delivered atomically. Valid YANG
structures are: `[ list, container ]` and scale MUST be taken into
Copy link

@rgwilton rgwilton Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need go consider atomic list entries vs the whole list is atomic. I suspect that this would need different annotations.

Copy link
Author

@earies earies Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point to call out. So far, I believe every use-case of atomicity to date has been on a list entry level (each entry can be treated as an atomic unit) - I am currently unaware of a scenario in which all list entries would be mandated to be delivered atomically but it is very well possible.

To the point of another possible annotation, what if we cleaned up the verbiage here to something like:

If the data content is modeled in the YANG language, a YANG extension SHOULD be
annotated on a corresponding structure to be delivered atomically.  Valid YANG
structures are: `[ list, container ]` and scale MUST be taken into consideration with
respect to atomic annotations.

When an annotation exists on a container, all child nodes of that container are to be
delivered atomically within a single `Notification` message.

When an annotation exists on a list, all child nodes of a single list entry are to be
delivered atomically within a single `Notification` message.  Delivering _all_ list entries
atomically is not currently supported.  Should the need arise, a future extension to
annotate at the list level can be taken into consideration.

Then follow-up w/ a description update to the oc-ext:telemetry-atomic extension detailing out this same ruleset w/ a reference to the spec section.

If we encounter a use-case of wanting to attach an annotation to a list to indicate all entries to be delivered atomically, this would then call for a new extension + spec update in the future.

WDYT?

consideration with respect to atomic annotations.

Example `oc-ext:telemetry-atomic` annotation from OpenConfig YANG modeling:

```
list next-hop {
key "index";

oc-ext:telemetry-atomic;
description
"A next-hop associated with the forwarding instance.";

leaf index {
...
}
...
}
```

For non-OpenConfig YANG modeled data, custom extensions MAY be used for similar
intent. This YANG extension then directly correlates to the usage of the gNMI
Notification `atomic` field being set to `true`.

If the data content is NOT modeled in the YANG language, an implementation MAY
choose when to set or not set the `atomic` field to true when sending atomic
datasets out of the scope of the specification.

#### 3.5.2.3 Sending Telemetry Updates

When an update for a subscribed telemetry path is to be sent, a
Expand Down