| Internet-Draft | IOAM Packet-Triggered Reporting | February 2026 |
| Li, et al. | Expires 1 September 2026 | [Page] |
This document defines a packet-triggered statistics reporting extension for In-situ Operations, Administration, and Maintenance (IOAM). The extension specifies a 2-bit Cycle Identifier field that enables receiving nodes to trigger statistics reporting based on observed Cycle ID transitions in received packets. This document defines the Cycle ID field format, node processing procedures, and keepalive packet generation rules.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 1 September 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
In-situ Operations, Administration, and Maintenance (IOAM) [RFC9197] records operational and telemetry information within user data packets while they traverse a network path. Alternate marking methods for packet loss measurement rely on periodic color changes to delineate measurement intervals.¶
This document specifies a packet-triggered reporting extension that uses a four-value Cycle Identifier (Cycle ID) field. Receiving nodes observe Cycle ID transitions in arriving packets and use these transitions to trigger statistics reporting. This document defines the Cycle ID field encoding, procedures for encapsulating and decapsulating nodes, and the generation of keepalive packets to maintain measurement continuity.¶
The scope of this document is limited to the definition of the Cycle ID field and associated node behaviors. The transport of IOAM data and the encapsulation in specific protocols (e.g., IPv6, NSH, GRE) are outside the scope of this document.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document uses the terminology defined in [RFC9197]. The following additional terms are used in this document:¶
This section provides a non-normative overview of packet-triggered statistics reporting.¶
The encapsulating node assigns a Cycle ID value (0-3) to each packet based on the current measurement interval. The Cycle ID value increments sequentially (0, 1, 2, 3, 0, ...) as measurement intervals advance. When the decapsulating node receives a packet with a Cycle ID different from the previously received Cycle ID, it triggers the reporting of statistics accumulated during the earlier interval.¶
To ensure that statistics reporting is triggered even during periods of no user traffic, the encapsulating node generates keepalive packets when no user data packets have been transmitted during an interval transition.¶
+---------------+ +---------------+
| Encapsulating | Cycle ID in IOAM Header | Decapsulating |
| Node | ---------------------------> | Node |
+---------------+ +---------------+
| |
| 1. Assign Cycle ID |
| 2. Maintain per-cycle counters |
| 3. Generate keepalive if needed |
| |
| 1. Detect Cycle ID change
| 2. Trigger stats report
| 3. Update local Cycle ID
The Cycle ID field is carried within the IOAM Option-Type header. The field format is defined as follows:¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Cycle ID |K| Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The fields are defined as follows:¶
The following Cycle ID values are defined:¶
| Value | Binary | Description |
|---|---|---|
| 0 | 00 | Measurement Interval 0 |
| 1 | 01 | Measurement Interval 1 |
| 2 | 10 | Measurement Interval 2 |
| 3 | 11 | Measurement Interval 3 |
This section specifies the normative procedures for encapsulating nodes.¶
The encapsulating node MUST maintain a current Cycle ID value for each IOAM flow. The encapsulating node MUST assign the current Cycle ID value to all packets belonging to that flow.¶
The encapsulating node MUST increment the Cycle ID value at the beginning of each new measurement interval. The increment operation MUST be performed modulo 4:¶
new_cycle_id = (current_cycle_id + 1) mod 4¶
The duration of a measurement interval is a local configuration parameter. The default measurement interval duration is 1 second. Implementations SHOULD support configurable measurement interval durations in the range of 100 milliseconds to 60 seconds.¶
The encapsulating node MUST maintain per-flow, per-Cycle-ID statistics counters. At minimum, the following counters MUST be maintained:¶
The encapsulating node MUST maintain statistics for all four Cycle ID values (0, 1, 2, 3) simultaneously.¶
+----------+--------------+--------+--------+--------+--------+ | Flow ID | Current | Cyc 0 | Cyc 1 | Cyc 2 | Cyc 3 | | | Cycle ID | Stats | Stats | Stats | Stats | +----------+--------------+--------+--------+--------+--------+ | <flow> | 0|1|2|3 | pkt/ | pkt/ | pkt/ | pkt/ | | | | byte | byte | byte | byte | +----------+--------------+--------+--------+--------+--------+
The encapsulating node MUST report statistics with a two-interval delay relative to the current Cycle ID. This delay ensures that all packets from a given interval have been processed before reporting.¶
The reporting relationship is defined as follows:¶
| Current Cycle ID | Report Statistics for Cycle ID |
|---|---|
| 0 | 2 |
| 1 | 3 |
| 2 | 0 |
| 3 | 1 |
The reporting schedule MAY be expressed as:¶
report_cycle_id = (current_cycle_id + 2) mod 4¶
The encapsulating node MUST generate a keepalive packet when a Cycle ID transition occurs and no user data packets were transmitted during the ending interval.¶
The encapsulating node MUST track whether at least one user data packet has been transmitted during each measurement interval. The encapsulating node SHOULD implement this tracking using a per-flow, per-Cycle-ID flag.¶
Upon Cycle ID transition, if the tracking flag indicates no user data packets were transmitted during the ending interval, the encapsulating node MUST generate and transmit a keepalive packet with the following properties:¶
Keepalive packets MUST NOT be counted in the packet statistics for packet loss calculation. Implementations MUST distinguish keepalive packets from user data packets in statistics counters.¶
If the encapsulating node is unable to insert the Cycle ID field due to insufficient header space, the node MUST forward the packet without IOAM information and SHOULD increment an error counter.¶
If the encapsulating node detects an invalid Cycle ID value in its local state (i.e., a value outside the range 0-3), the node MUST reset the Cycle ID to 0 and SHOULD log the error condition.¶
This section specifies the normative procedures for transit nodes.¶
A transit node that supports packet-triggered reporting MUST perform the following operations for each received packet containing a Cycle ID field:¶
Transit nodes MUST NOT modify the Cycle ID field or the K flag.¶
Transit nodes SHOULD NOT maintain timers for statistics reporting. Transit nodes MAY trigger local statistics reporting based on observed Cycle ID transitions, using the same procedures as decapsulating nodes.¶
If a transit node receives a packet with an invalid Cycle ID value (outside the range 0-3), the node MUST forward the packet without updating statistics and SHOULD increment an error counter.¶
If a transit node receives a packet with a malformed Cycle ID field (e.g., truncated header), the node SHOULD forward the packet according to local policy and MUST increment an error counter.¶
This section specifies the normative procedures for decapsulating nodes.¶
The decapsulating node MUST maintain the following per-flow state:¶
Upon receiving the first packet for a flow, the decapsulating node MUST set the initialization flag and record the received Cycle ID as the last received Cycle ID. The decapsulating node MUST NOT trigger statistics reporting for the first received packet.¶
For each received packet after initialization, the decapsulating node MUST compare the packet's Cycle ID with the last received Cycle ID.¶
If the Cycle ID values differ, the decapsulating node MUST:¶
If the Cycle ID values are equal, the decapsulating node MUST update only the statistics counter for the current Cycle ID.¶
When the decapsulating node receives a packet with the K flag set to 1, the node MUST:¶
If the decapsulating node receives a packet with an invalid Cycle ID value, the node MUST discard the Cycle ID information from that packet, MUST NOT trigger statistics reporting based on that packet, and SHOULD increment an error counter.¶
If the decapsulating node detects a Cycle ID sequence gap (e.g., transition from 0 to 2, skipping 1), the node SHOULD log this condition and MAY trigger reporting for all skipped intervals. The specific behavior for sequence gaps is implementation-defined.¶
The Cycle ID transitions through four states in a fixed sequence. The state machine is defined as follows:¶
Interval Timer Expiry
+-----+ +-----+
| | +------------------> | |
| 0 | | | 1 |
| | <-+ | |
+-----+ | +-----+
^ | |
| | Interval | Interval
| | Timer | Timer
| | Expiry | Expiry
| | v
+-----+ | +-----+
| | | | |
| 3 | <-+ | 2 |
| | +------------------> | |
+-----+ Interval Timer +-----+
Expiry
The Cycle ID value MUST transition in the sequence: 0 -> 1 -> 2 -> 3 -> 0 (repeating). No other transition sequences are valid.¶
The transition from one Cycle ID value to the next MUST occur only at measurement interval boundaries as determined by the encapsulating node's local timer.¶
Implementations supporting this specification SHOULD expose the following configuration parameters:¶
The security considerations of [RFC9197] apply to this extension. The following additional considerations are specific to the Cycle ID mechanism.¶
The Cycle ID field is a 2-bit value that indicates the measurement interval. An on-path attacker could modify the Cycle ID value, causing incorrect statistics reporting at the decapsulating node. Implementations operating outside a single administrative trust domain SHOULD protect IOAM data integrity using mechanisms such as those described in [RFC9197] Section 5.¶
The keepalive packet generation mechanism could be abused by an attacker who suppresses user data packets, causing the encapsulating node to generate keepalive packets continuously. Implementations SHOULD monitor keepalive generation rates and alert operators when abnormal patterns are detected.¶
Statistics counters maintained by transit and decapsulating nodes are local state and are not exposed in the data plane. Access to these counters through management interfaces SHOULD be protected by authentication and authorization mechanisms.¶
This document requests IANA to allocate a new Option-Type from the "IOAM Option-Type" registry defined in [RFC9197].¶
| Value | Description | Reference |
|---|---|---|
| TBD1 | IOAM Cycle ID Option | [This Document] |
This document requests IANA to create a new registry titled "IOAM Cycle ID Flags" under the "In-situ OAM (IOAM)" registry group.¶
The registry contains 1-bit flags. The initial contents of the registry are:¶
| Bit Position | Name | Description | Reference |
|---|---|---|---|
| 0 | K | Keepalive Flag | [This Document] |
Future assignments in this registry require Standards Action [RFC8126].¶
This appendix provides non-normative examples of packet-triggered reporting behavior.¶
Consider a flow with continuous traffic. The encapsulating node operates with a 1-second measurement interval:¶
Time (s) Cycle ID Encap Action Decap Action
-------- -------- ------------------ ------------------
0.0-1.0 0 Assign CID=0 Receive CID=0
Count packets Count packets
(Initialize)
1.0-2.0 1 Assign CID=1 Receive CID=1
Count packets Trigger: report CID=3
(No data for CID=3)
Count packets
2.0-3.0 2 Assign CID=2 Receive CID=2
Report CID=0 stats Trigger: report CID=0
Count packets Count packets
3.0-4.0 3 Assign CID=3 Receive CID=3
Report CID=1 stats Trigger: report CID=1
Count packets Count packets
¶
Consider a flow with intermittent traffic where no packets are transmitted during Cycle ID=1:¶
Time (s) Cycle ID Traffic Encap Action -------- -------- -------- --------------------------- 0.0-1.0 0 Present Assign CID=0, count packets 1.0-2.0 1 None Generate keepalive (CID=1, K=1) 2.0-3.0 2 Present Assign CID=2, count packets¶