IPFIX Export of Buffer Snapshots

Introduction Buffer measurements taken during a short congestion event can describe different resource sets and different sample instants. A collector receiving two records for one queue cannot treat them as evidence that two distinct queues were measured. Similarly, a complete transport stream cannot establish whether the device successfully read every object in its configured monitoring scope. The interoperability problem addressed here is the interpretation of a multi-object snapshot between independently implemented IPFIX Exporting and Collecting Processes. This document defines a shared interpretation of object identity, acquisition counts, sampling span, and finalization. It uses the IPFIX protocol and information model . The proposed profile is appropriate when IPFIX is already the export channel and the receiver needs these snapshot properties. Deployments using an existing management interface with adequate grouping and timing semantics need not add another export protocol. Independent deployment demand for this profile remains to be established.

Relationship to Existing Work The SAI queue and buffer interfaces expose occupancy and watermark statistics . Those interfaces establish that buffer observations are useful implementation data. They do not themselves establish demand for this IPFIX profile or specify its collector finalization rules. IPFIX common properties and structured data can associate or aggregate measurements. They remain alternatives for future encodings. This profile specifies the meaning of capture counts and bounds, then uses ordinary Data Records and an Options Data Record so a snapshot can span several IPFIX Messages without requiring a single large structured record. YANG-Push provides another telemetry delivery mechanism. The QoS model and data manifest are related work in progress. Their configuration, subscription, and metadata functions are not replaced. This profile does not claim that IPFIX has an intrinsic performance advantage over those mechanisms. Delay performance export describes packet-path delay metrics, while the packet discard model describes discard reporting. An occupancy sample is neither a path-delay measurement nor a discard counter. This profile introduces no alternate discard taxonomy and MUST NOT infer a particular discard cause solely from occupancy.

Requirements Language The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology and Scope IPFIX terms follow and . A buffer object is an egress queue, ingress priority group, shared buffer pool, or headroom pool with defined occupancy accounting. A snapshot scope is a finite set of distinct objects frozen at the start of one capture attempt. N is the number of objects in the frozen scope. C is the number of distinct objects successfully captured before acquisition ends. D is the number of distinct object records accepted by the collector before final metadata. The metadata declares N and C; the collector derives D. A snapshot is identified by (Transport Session, Observation Domain ID, snapshotId). A seal is the single final Snapshot Metadata Options Data Record. It closes the export of that identifier. Capture-complete is an exporter assertion that C equals N. Delivery-complete is a collector result that the sealed records are internally consistent and D equals C. These properties are distinct from inventory-verified coverage, simultaneous sampling, measurement precision, and authenticity of the exporter. Neither counts nor transport reliability prove that a compromised exporter sampled the asserted objects. Metering Process Exporting Process Collecting Process freeze scope N ordered TCP stream buffer distinct keys capture C objects -> object(k), ... -> validate and count D finalize metadata metadata(k) [seal] -> close k; emit result next snapshot k+1 retain closed-ID floor

Object Identity and Accounting Within one Transport Session and Observation Domain, the canonical key is (bufferObjectType, applicable interface index, bufferObjectIndex). For types without interface scope the interface component is absent. Indices need not be contiguous. Type and interface scope are part of the key; an object index alone is insufficient. Initial Buffer Object Types

Value	Object	Required interface IE	Index scope
0	Reserved	None	Invalid
1	Egress queue	egressInterface (14), nonzero	Egress interface
2	Ingress priority group	ingressInterface (10), nonzero	Ingress interface
3	Shared buffer pool	None	Observation Domain
4	Headroom pool	None	Observation Domain

The exporter MUST ensure that each key denotes one resource and one accounting interpretation for the Transport Session. If a key is reassigned, an interface index is reused, or its accounting interpretation changes, the exporter MUST establish a new Transport Session before exporting the changed meaning. Adding or removing keys between snapshot scopes does not change the meanings of surviving keys. Snapshot scope membership MUST be frozen before acquisition and MUST contain no duplicate keys. Every captured object MUST belong to that scope. N and C alone do not identify uncaptured objects. A collector requiring inventory-verified coverage MUST obtain an independently provisioned scope inventory, bind it to the relevant session and capture attempt, and compare the received keys with it. This profile does not transport that inventory or negotiate its version. bufferOccupancyOctets is a gauge of currently accounted buffer storage, not a traffic counter, watermark, capacity, or threshold. bufferAccountingGranularity is the nonzero accounting quantum in octets. An exact cell counter with quantum G is exported as allocated cells multiplied by G. A quantum of one permits octet resolution but does not prove estimator accuracy. The approximateOccupancy flag qualifies an estimated measurement even when its quantum is one. Each occupancy MUST be a multiple of its stated quantum. An estimator MUST be expressed in that same accounting unit and flagged approximate; the exporter MUST document its rounding and estimation method. Values that overflow unsigned64 MUST be omitted from acquisition, reducing C, rather than wrapped or saturated without qualification. Overlapping queue and pool measurements MUST NOT be summed unless an external accounting model establishes that the quantities are disjoint.

Capture Contract At the start of each attempt the exporter MUST allocate a nonzero snapshotId greater than every previously allocated identifier in the same Transport Session and Observation Domain. Identifiers MUST NOT wrap or be reused. If monotonic allocation or object identity cannot be preserved after restart, the exporter MUST open a new session. Allocation need not be contiguous; identifier gaps MUST NOT be interpreted as a count of physical events or lost snapshots. Acquisition MUST finish or terminate before any record for the snapshot is exported. Metadata and the captured object set MUST then remain immutable. The exporter MUST preserve 0 <= C <= N and set incompleteCapture if and only if C < N. C MUST NOT be reduced later to conceal an export-queue drop. Empty scopes are permitted: N=C=0 describes an empty selection, not successful observation of any resource. Capture MUST NOT change live packet counters, queue admission, scheduling, ECN marking, PFC behavior, or discard policy. Implementations SHOULD bound capture work and export rate so observation does not materially impair forwarding. Trigger suppression and coalescing MAY occur before an attempt starts; their local policy MUST be documented.

Temporal Bound and Flags snapshotCaptureSpanNanoseconds is a conservative upper bound on the separation between the earliest and latest sample instants among the C captured objects. The bound MUST include uncertainty in locating those instants. A hardware simultaneity guarantee, a monotonic measurement, or a justified deterministic readout bound MAY be used. Subtracting adjustable wall-clock timestamps MUST NOT be used to establish the bound. For C > 0, zero span is permitted only when simultaneous capture is established; a single exact observation satisfies this condition. A positive finite span MUST set nonAtomic. Zero span MUST clear nonAtomic and spanUnknown. If simultaneity cannot be established, the exporter MUST use a positive conservative bound, or UINT64_MAX if no finite bound is known. UINT64_MAX is reserved for unknown span and MUST set both spanUnknown and nonAtomic. For C=0, the span MUST be UINT64_MAX and both spanUnknown and nonAtomic MUST be set. A bound on C measurements says nothing about the N-C uncaptured objects. The collector MUST validate these combinations before reporting delivery completeness.

Optional Wall-Clock Context The final metadata MAY contain observationTimeNanoseconds (IE 325) when C>0, referring to the first sample. This IE uses the IPFIX dateTimeNanoseconds type: the NTP seconds and fractional-seconds representation specified by , rather than integer Unix nanoseconds. It MUST be absent when C=0. Cross-device correlation requires separately established clock accuracy and synchronization; timestamp syntax does not provide that assurance.

Ordered IPFIX Export Profile This profile MUST use IPFIX over TCP as specified in . UDP and SCTP are outside this profile. Exporters and collectors MUST support TLS for IPFIX and SHOULD use mutually authenticated TLS 1.3 on deployments that support it. Plain TCP is permissible only under a deployment security policy that supplies equivalent protection and access control. The profile is configured out of band at both peers. It defines no new IPFIX version or transport negotiation. Before IANA assignment, experiments MUST use enterprise-specific IEs under an appropriate Private Enterprise Number and an explicitly agreed mapping. Symbolic TBD labels are not wire identifiers. An endpoint MUST NOT infer this profile solely from numeric experimental identifiers used by another enterprise.

Templates and Field Presence Templates MUST precede their Data Records in the session. Template lifetimes, Set framing, padding, and Sequence Numbers follow . A profile record MUST contain each required IE exactly once, with its full field length shown below; reduced-size encoding is not used for these fields in this profile. Extra IEs MAY carry context if they do not change the meaning of required fields. Snapshot metadata MUST use an Options Template with snapshotId as its only scope field and the other five required fields as non-scope fields. The protocol Observation Domain ID and Transport Session supply the outer scope. A metadata record is always a final seal, never a preliminary estimate. Object records use an ordinary Data Template. Egress queues MUST include egressInterface and MUST NOT include ingressInterface; ingress priority groups MUST include ingressInterface and MUST NOT include egressInterface; shared and headroom pools MUST include neither. Separate Templates MUST be used where field presence differs. A field cannot be omitted on selected records of the same Template. These rules avoid assigning new sentinel semantics to the existing interface IEs. Required Fields and Lengths

Record	Fields in recommended order (length in octets)	Required fields
Final metadata	snapshotId (8, scope); snapshotExpectedObjectCount (4); snapshotCapturedObjectCount (4); snapshotCaptureSpanNanoseconds (8); snapshotTriggerType (1); snapshotFlags (2)	6; scope count 1
Egress queue	snapshotId (8); bufferObjectType (1); egressInterface (4); bufferObjectIndex (4); bufferOccupancyOctets (8); bufferAccountingGranularity (4)	6
Ingress priority group	snapshotId (8); bufferObjectType (1); ingressInterface (4); bufferObjectIndex (4); bufferOccupancyOctets (8); bufferAccountingGranularity (4)	6
Pool	snapshotId (8); bufferObjectType (1); bufferObjectIndex (4); bufferOccupancyOctets (8); bufferAccountingGranularity (4)	5

Field order is determined by the Template, not by the example order in the table. Required metadata occupies 27 octets per record; queue and priority-group records occupy 29, and pool records occupy 25, excluding optional fields and IPFIX framing. Unknown optional IEs MUST NOT change snapshot counting or finalization.

Snapshot Serialization and Seal For each Transport Session and Observation Domain, the exporter MUST emit snapshots in increasing snapshotId order. All object records of one snapshot MUST precede its single metadata seal. Records of another snapshot in that same Observation Domain MUST NOT be interleaved. Different Observation Domains and unrelated IPFIX records MAY interleave. Ordering means the order of records in Sets and IPFIX Messages as parsed from the TCP byte stream. The exporter MUST emit every captured object exactly once in normal operation. A collector nevertheless tolerates identical duplicates before the seal. The exporter MUST emit no further record for an identifier after its seal, including repeated metadata. If a snapshot cannot be fully exported, the exporter MUST omit its seal or terminate the session. It MAY move to a larger identifier, thereby abandoning the unfinished earlier snapshot. A seal is emitted only after all C records have been handed to the same ordered stream. TCP delivery does not guarantee that internal application queues preserved them. D=C at the seal is the independent application check. The final record permits bounded receiver history; a later conflicting record is a protocol violation, not an amendment of the finalized snapshot.

Collector State and Validation A collector MUST parse and process this profile in stream order even if internal workers run concurrently. For each Observation Domain it maintains a closed-ID floor F (initially zero), at most one active identifier K, and a bounded map of accepted object keys for K. F represents identifiers that MUST NOT be reopened. This requires no retained object cache for completed snapshots. Before allocating state, the collector MUST enforce configured limits on sessions, Observation Domains per session, records and bytes per active snapshot, processing rate, and reassembly duration. It MUST NOT allocate memory proportional to an untrusted N or C. Limits and incomplete-result reasons MUST be exposed to the application. Ordered Collector Transitions

Input or event	Required processing
Identifier 0	Reject as invalid; do not create a snapshot
Identifier k <= F	Discard as a late or repeated closed record; report a protocol diagnostic
First k > F with no active K	Set F=k-1; create K=k
k > active K	Finalize K as incomplete (missing seal); set F=k-1; start K=k
F < k < active K	Impossible after the start rule; reject defensively
Object for active K	Validate key and fields; accept one value per key; handle duplicates below
Seal for active K, or seal starting a new k	Validate metadata, classify the result, then set F=k and release all active state
Timeout, size cap, or invalid record for K	Finalize K as expired, resource-limited, or invalid; set F=K; release active state
Transport Session ends	Close any active snapshot as incomplete; discard session floors and Templates

For each accepted object, the collector MUST validate the type-specific interface rule, nonzero granularity, and occupancy divisibility by granularity. Identical duplicates are compared by decoded required fields and counted once; optional context is not part of the count. A duplicate with a different required value MUST invalidate the active snapshot. An unrecognized object type prevents interpreted delivery completeness; the collector MUST close that snapshot as unsupported and retire its identifier. At a seal the collector MUST check C<=N, incompleteCapture==(C<N), the span/flag combinations in , and the C=0 timestamp rule. If D>C it MUST report invalid. If D<C it MUST report incomplete delivery. If D=C and all checks pass it MUST report delivery-complete. A seal received before its purported objects closes as incomplete; later records for it MUST NOT revive it. Unknown trigger values are descriptive context and do not invalidate an otherwise well-formed snapshot. Unknown flag bits are semantic qualifications: the collector MAY report the structural D=C result, but MUST label the result unsupported-qualified and MUST NOT report unqualified delivery or acquisition completeness. This version has no negotiated extension that relaxes its validation rules. A result MUST separately expose delivery status, exporter-asserted acquisition status (complete, partial, or empty scope), simultaneity/span, approximation, and any inventory verification. N>0,C=0 with valid metadata is complete delivery of a failed capture, never a report that N objects have zero occupancy. C=N without an inventory check is a source assertion plus consistency check, not independent proof of scope coverage. Closed results are immutable under this profile. Records with k<=F are diagnostic violations and MUST NOT reopen, complete, or silently replace an archived result. A collector MAY terminate a session after such a violation. Finality applies to the accepted sealed prefix, not to the truthfulness of a peer that later violates the protocol. This explicit rule replaces indefinite post-delivery conflict retention.

Information Element Definitions The following proposed IEs use the specification template of and review guidance of . All have status current and reference this document. IANA identifiers remain TBD until assigned. Units are taken from the existing IPFIX units registry; object counts use none, not a newly invented objects unit.

snapshotId Identifier scoped by Transport Session and Observation Domain. It increases for successive capture attempts. The final Options Data Record for the identifier seals the snapshot; subsequent records for it are prohibited. Registration Properties

Property	Value
Name	snapshotId
ElementId	TBD1
Abstract Data Type	unsigned64
Data Type Semantics	identifier
Units	none
Range	1..18446744073709551615
Status	current
Reference	RFC XXXX (this document)

snapshotExpectedObjectCount N: the number of distinct objects in the scope frozen at acquisition start. This is a count, not an inventory of their identities. Registration Properties

Property	Value
Name	snapshotExpectedObjectCount
ElementId	TBD2
Abstract Data Type	unsigned32
Data Type Semantics	quantity
Units	none
Range	0..4294967295
Status	current
Reference	RFC XXXX (this document)

snapshotCapturedObjectCount C: the number of distinct scoped objects successfully captured before acquisition ends. It cannot exceed N and cannot be changed to conceal a subsequent export failure. Registration Properties

Property	Value
Name	snapshotCapturedObjectCount
ElementId	TBD3
Abstract Data Type	unsigned32
Data Type Semantics	quantity
Units	none
Range	0..4294967295
Status	current
Reference	RFC XXXX (this document)

snapshotCaptureSpanNanoseconds Conservative upper bound on the separation of sample instants among captured objects, including uncertainty. Zero means established simultaneity. UINT64_MAX means unknown and is required for C=0. Registration Properties

Property	Value
Name	snapshotCaptureSpanNanoseconds
ElementId	TBD4
Abstract Data Type	unsigned64
Data Type Semantics	quantity
Units	nanoseconds
Range	0..18446744073709551615
Status	current
Reference	RFC XXXX (this document)

snapshotTriggerType Class of local stimulus that initiated capture. Initial assignments are in the Snapshot Trigger Types registry. This value does not identify the root cause of congestion. Registration Properties

Property	Value
Name	snapshotTriggerType
ElementId	TBD5
Abstract Data Type	unsigned8
Data Type Semantics	identifier
Units	none
Range	0..255
Status	current
Reference	RFC XXXX (this document)

snapshotFlags Mask qualifying acquisition completeness, simultaneity, span knowledge, and measurement approximation. Masks and receiver handling are defined below. Registration Properties

Property	Value
Name	snapshotFlags
ElementId	TBD6
Abstract Data Type	unsigned16
Data Type Semantics	flags
Units	none
Range	0..65535
Status	current
Reference	RFC XXXX (this document)

bufferObjectType Object class. The class determines whether the index is scoped by an egress interface, ingress interface, or Observation Domain. Zero is reserved. Registration Properties

Property	Value
Name	bufferObjectType
ElementId	TBD7
Abstract Data Type	unsigned8
Data Type Semantics	identifier
Units	none
Range	1..255
Status	current
Reference	RFC XXXX (this document)

bufferObjectIndex Object index within the namespace selected by bufferObjectType and its applicable interface. It remains semantically stable for the Transport Session. Registration Properties

Property	Value
Name	bufferObjectIndex
ElementId	TBD8
Abstract Data Type	unsigned32
Data Type Semantics	identifier
Units	none
Range	0..4294967295
Status	current
Reference	RFC XXXX (this document)

bufferOccupancyOctets Instantaneous accounted storage of the identified object, in octets, including allocation overhead where applicable. The value is a multiple of bufferAccountingGranularity and may be flagged approximate. Registration Properties

Property	Value
Name	bufferOccupancyOctets
ElementId	TBD9
Abstract Data Type	unsigned64
Data Type Semantics	quantity
Units	octets
Range	0..18446744073709551615
Status	current
Reference	RFC XXXX (this document)

bufferAccountingGranularity Accounting quantum in octets for the object. One denotes octet resolution. A larger value denotes the cell or allocation-block quantum. This field does not establish estimator accuracy. Registration Properties

Property	Value
Name	bufferAccountingGranularity
ElementId	TBD10
Abstract Data Type	unsigned32
Data Type Semantics	quantity
Units	octets
Range	1..4294967295
Status	current
Reference	RFC XXXX (this document)

Flag Masks snapshotFlags is encoded as an unsigned16 in network byte order. The numeric masks below are authoritative. If bits are displayed from most significant to least significant, masks 0x0008 through 0x0001 occupy displayed positions 12 through 15. This display convention does not follow from byte order alone. Snapshot Flags

Mask	Name	Rule
0x0001	incompleteCapture	Set exactly when C<N
0x0002	nonAtomic	Set when simultaneous capture is not established, or C=0
0x0004	spanUnknown	Set exactly when span=UINT64_MAX
0x0008	approximateOccupancy	Set if any captured value is an estimate; clear for C=0
0xFFF0	Unassigned	Exporter sets zero; receiver treats nonzero as unsupported qualification

For C=0, approximateOccupancy MUST be clear. For simultaneous C>0 capture the span MUST be zero. These rules make the defined flags and span mutually checkable without asserting anything about uncaptured objects.

Examples and Implementation Checks Collector Test Cases

Object records before seal	Final metadata	Expected result
Q0=128, Q1=256; G=128	N=2,C=2,span=0,flags=0	Complete delivery; source asserts complete simultaneous capture
Q0=128, Q0=128; G=128	N=2,C=2,span=20,flags=2	D=1; incomplete at seal
Q0=128, Q0=128, Q1=256	N=2,C=2,span=20,flags=2	D=2; complete; duplicate counted once
Q0=128, Q0=256	Any seal	Conflicting duplicate; invalid before seal
Q0=128, Q1=256	N=3,C=2,span=20,flags=3	Complete delivery; partial acquisition
None	N=3,C=0,span=UINT64_MAX,flags=7	Complete delivery; failed capture
None	N=0,C=0,span=UINT64_MAX,flags=6	Complete delivery; empty scope
Q0 only; then larger snapshot ID	No seal	Earlier snapshot incomplete; old ID cannot reopen
Seal arrives first, then Q0	N=1,C=1,span=0,flags=0	Incomplete at seal; late Q0 discarded
Q0=129; G=128	Any seal	Invalid accounting quantum
Q0 arrives after completed seal	Previously valid N=C=D	Closed result unchanged; protocol violation reported

A conforming implementation test SHOULD include two Observation Domains interleaving on one TCP stream, Template replacement rules, session restart with the same numeric snapshotId, timeout followed by a late seal, memory-cap exhaustion, unknown flags, malformed interface fields, and count overflow. Tests of the state machine alone do not demonstrate hardware capture accuracy or independent interoperability.

IANA Considerations IANA is requested to register the ten IEs in in the IPFIX Information Elements registry . No existing IE allocation is changed. Numeric TBD values MUST NOT be transmitted as if assigned.

Value Subregistries IANA is requested to create IPFIX Snapshot Trigger Types (unsigned8) and IPFIX Buffer Object Types (unsigned8), using Expert Review . Each entry records Value, Name, Description, and Reference. Snapshot Trigger Types initially assigns 0 Unknown, 1 Management request, 2 Periodic timer, 3 Occupancy threshold crossing, 4 Buffer congestion discard, and 5 Local PFC assertion; 6-255 are unassigned. Buffer Object Types uses the values in ; 5-255 are unassigned. A trigger registration MUST describe the observed stimulus without claiming causal diagnosis. An object-type registration MUST define its identity, interface scope, accounting meaning, and Template field presence. Experts should prefer existing types when their semantics suffice and require a public specification for a new interpretation. Allocating a new type does not make older collectors understand it.

Flag Subregistry IANA is requested to create IPFIX Snapshot Flags with columns Numeric Mask, Name, Meaning, and Reference. The four assigned masks and the unassigned mask space are in . New assignments use Standards Action and MUST specify their effect on validation, finalization, and older collectors. The numeric mask convention MUST be retained.

Security Considerations The IPFIX security considerations in apply. Occupancy and trigger reports can reveal workload timing, topology, and resource stress. Export destinations MUST be authorized. Implementations MUST support transport protection, apply access controls, and limit retention according to deployment policy. TLS authenticates a peer and protects its messages; it cannot make a compromised exporter truthful. N, C, identifiers, and rate are untrusted inputs. The collector limits in are mandatory. A peer can deliberately send a very large identifier, which retires smaller identifiers for that session; this affects only that authenticated session and Observation Domain. It MUST NOT affect another exporter or session. Replay from an earlier session MUST NOT be merged with current reassembly state. The absence of a snapshot or an incomplete result MUST NOT be interpreted as absence of congestion. Trigger suppression, an overloaded exporter, and resource limits can bias the observations. Using the telemetry to drive control decisions requires independent safeguards; this document defines no automatic congestion-control response.