Skip to content
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
625d70a
telemetry: pad sharedRingBuffer header to prevent false sharing
pooriaPoorsarvi Jul 30, 2026
bb9e912
telemetry: cache opposing index and mask in ring buffer hot paths
pooriaPoorsarvi Jul 30, 2026
e2059b3
telemetry: add test for cached position seeding on reattach
pooriaPoorsarvi Jul 30, 2026
f18d9fa
Merge branch 'main' into opt/telemetry-sharedRingBuffer
iyastreb Jul 31, 2026
7a2ba6d
telemetry: keep version at a fixed offset across layout versions
pooriaPoorsarvi Aug 3, 2026
4d046c3
telemetry: assert bufferHeader field offsets
pooriaPoorsarvi Aug 3, 2026
bff1a5e
telemetry: seed all cached values on the create path
pooriaPoorsarvi Aug 3, 2026
6027684
telemetry: validate BufferHeader layout in the Python reader
pooriaPoorsarvi Aug 5, 2026
62b500e
Merge branch 'main' into opt/telemetry-sharedRingBuffer
pooriaPoorsarvi Aug 13, 2026
ba9a916
Merge branch 'main' into opt/telemetry-sharedRingBuffer
ColinNV Sep 14, 2026
bc2ed49
Merge remote-tracking branch 'upstream/main' into opt/telemetry-share…
pooriaPoorsarvi Sep 15, 2026
e7c3c36
Merge remote-tracking branch 'upstream/main' into opt/telemetry-share…
pooriaPoorsarvi Oct 4, 2026
49fc7cc
Merge branch 'main' into opt/telemetry-sharedRingBuffer
ColinNV Oct 5, 2026
d075f96
telemetry: keep a compatible ring file across producer restart
pooriaPoorsarvi Oct 12, 2026
8fd0a24
telemetry: test consumer across producer restart and replacement
pooriaPoorsarvi Oct 12, 2026
684dd1e
Merge remote-tracking branch 'upstream/main' into opt/telemetry-share…
pooriaPoorsarvi Oct 19, 2026
19941bf
telemetry: bump TELEMETRY_VERSION to 6
pooriaPoorsarvi Oct 19, 2026
6cad430
telemetry: test push and pop cache reloads on a full ring
pooriaPoorsarvi Oct 19, 2026
3900163
telemetry: document producer restart behaviour
pooriaPoorsarvi Oct 19, 2026
5536cae
telemetry: test cached positions on both producer restart paths
pooriaPoorsarvi Oct 19, 2026
c0d8121
telemetry: gate ring reuse on an attached consumer
pooriaPoorsarvi Oct 22, 2026
ef3069e
telemetry: test producer restart without a consumer
pooriaPoorsarvi Oct 22, 2026
b253e52
Merge remote-tracking branch 'upstream/main' into opt/telemetry-share…
pooriaPoorsarvi Oct 22, 2026
ffe4121
telemetry: copy events out of the ring in the Python reader
pooriaPoorsarvi Oct 23, 2026
aa333c5
Merge branch 'main' into opt/telemetry-sharedRingBuffer
ColinNV Oct 23, 2026
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
2 changes: 1 addition & 1 deletion docs/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ Following sections applied specifically for configuration and usage of cyclic bu

Telemetry data is stored in shared memory files with the agent name passed when creating the agent.

`TELEMETRY_VERSION` is the binary layout version of `nixlTelemetryEvent` as serialized in the shared-memory cyclic buffer. Bump it whenever the struct's size, field offsets, or enum widths change, or when a new event type is added to the stream (readers must know the full event-type set). Readers exact-match this value; the C++ shared-ring-buffer path unlinks the file on mismatch, while the Python example raises a `RuntimeError`. There is no backward-compatibility path. The current version is `4`: it was bumped from `3` when the `agent_telemetry_events_dropped` event type (`AGENT_TELEMETRY_EVENTS_DROPPED`) was added.
`TELEMETRY_VERSION` is the binary layout version of the shared-memory cyclic buffer, covering its header, data placement, and the `nixlTelemetryEvent` entries serialized in it. Bump it whenever the buffer header layout or the struct's size, field offsets, or enum widths change, or when a new event type is added to the stream (readers must know the full event-type set). Readers exact-match this value; the C++ shared-ring-buffer path unlinks the file on mismatch, while the Python example raises a `RuntimeError`. There is no backward-compatibility path. The current version is `5`: it was bumped from `4` when the buffer header was padded to two 256-byte-aligned blocks (512 bytes) to eliminate false sharing between `write_pos` and `read_pos`, which moved `capacity`, `mask`, `read_pos`, and the data-array offset; `version` deliberately stays at byte offset 16 across layout versions so a reader on a mismatched file always reads a real version field. Version `4` was bumped from `3` when the `agent_telemetry_events_dropped` event type (`AGENT_TELEMETRY_EVENTS_DROPPED`) was added.

### Using Telemetry Readers

Expand Down
58 changes: 48 additions & 10 deletions examples/python/telemetry_reader.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@
logger = logging.getLogger(__name__)

# Constants from telemetry_event.h
TELEMETRY_VERSION = 4
TELEMETRY_VERSION = 5
DESTRUCTIVE_INTERFERENCE_SIZE = 256

# NIXL telemetry event types (nixl_telemetry_event_type_t)
AGENT_TX_BYTES = 0
Expand Down Expand Up @@ -86,15 +87,44 @@ class BufferHeader(ctypes.Structure):

_pack_ = 1
_fields_ = [
("write_pos", ctypes.c_size_t),
("read_pos", ctypes.c_size_t),
("version", ctypes.c_uint32),
("expected_version", ctypes.c_uint32),
("capacity", ctypes.c_size_t),
("mask", ctypes.c_size_t),
("write_pos", ctypes.c_size_t), # [0, 8)
("capacity", ctypes.c_size_t), # [8, 16)
# version stays at offset 16 across layout versions (see cyclic_buffer.h)
("version", ctypes.c_uint32), # [16, 20)
("expected_version", ctypes.c_uint32), # [20, 24)
("mask", ctypes.c_size_t), # [24, 32)
(
"_pad_write",
ctypes.c_char * (DESTRUCTIVE_INTERFERENCE_SIZE - 32),
Comment thread
ColinNV marked this conversation as resolved.
Resolved
), # pad write_pos's interference-size block: [32, 256)
("read_pos", ctypes.c_size_t), # [256, 264)
(
"_pad_tail",
ctypes.c_char
* (DESTRUCTIVE_INTERFERENCE_SIZE - ctypes.sizeof(ctypes.c_size_t)),
), # match C++ compiler's tail padding: [264, 512)
]


# Mirror the static_asserts in cyclic_buffer.tpp so a layout drift fails.
# The pads are checked too since they are maintained by hand here, while
# the C++ compiler derives them from alignas.
if ctypes.sizeof(BufferHeader) != 2 * DESTRUCTIVE_INTERFERENCE_SIZE:
raise RuntimeError("BufferHeader layout drift: unexpected size")
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
for _field, _offset in [
("write_pos", 0),
("capacity", 8),
("version", 16),
("expected_version", 20),
("mask", 24),
("_pad_write", 32),
("read_pos", 256),
("_pad_tail", 264),
]:
if getattr(BufferHeader, _field).offset != _offset:
raise RuntimeError(f"BufferHeader layout drift: {_field} moved")


class SharedRingBuffer:
"""Python wrapper for the C++ SharedRingBuffer class"""

Expand All @@ -106,10 +136,16 @@ def __init__(self, file_path, version=TELEMETRY_VERSION):
self.header = None
self.data = None
self.buffer_size = None
self.cached_write_pos = 0
self.cached_mask = 0

self._open_file()
self._map_memory()

# Seed the cached positions on attaching to an existing buffer
self.cached_write_pos = self.header.write_pos
self.cached_mask = self.header.mask

def _open_file(self):
"""Open existing file"""
self.file_fd = os.open(self.file_path, os.O_RDWR)
Expand Down Expand Up @@ -188,12 +224,14 @@ def pop(self):
"""Pop an event from the buffer"""
read_pos = self.header.read_pos

if read_pos == self.header.write_pos:
return None
if read_pos == self.cached_write_pos:
self.cached_write_pos = self.header.write_pos
if read_pos == self.cached_write_pos:
return None

event = self.data[read_pos]

next_read = (read_pos + 1) & self.header.mask
next_read = (read_pos + 1) & self.cached_mask
self.header.read_pos = next_read

return event
Expand Down
2 changes: 1 addition & 1 deletion src/core/telemetry/telemetry_event.h
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ constexpr char TELEMETRY_BUFFER_SIZE_VAR[] = "NIXL_TELEMETRY_BUFFER_SIZE";
constexpr char TELEMETRY_RUN_INTERVAL_VAR[] = "NIXL_TELEMETRY_RUN_INTERVAL";
constexpr char TELEMETRY_ENABLED_METRICS_VAR[] = "NIXL_TELEMETRY_ENABLED_METRICS";

constexpr inline int TELEMETRY_VERSION = 4;
constexpr inline int TELEMETRY_VERSION = 5;
Comment thread
ColinNV marked this conversation as resolved.
Resolved

/**
* @enum nixl_telemetry_event_type_t
Expand Down
22 changes: 17 additions & 5 deletions src/utils/common/cyclic_buffer.h
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
Expand All @@ -18,6 +18,7 @@
#define _NIXL_CYCLIC_BUFFER_HPP

#include <atomic>
#include <cstddef>
#include <cstring>
#include <stdexcept>
#include <iostream>
Expand Down Expand Up @@ -50,13 +51,21 @@ template<typename T> class sharedRingBuffer {
capacity() const;

private:
// Hardcoded value instead of std::hardware_destructive_interference_size due to ABI;
// needs to be consistent across build and compilers.
// Conservatively set to 256 similar to GCC std::hardware_destructive_interference_size for ARM.
static constexpr size_t DESTRUCTIVE_INTERFERENCE_SIZE = 256;

struct bufferHeader {
Comment thread
ColinNV marked this conversation as resolved.
Resolved
std::atomic<size_t> write_pos{0};
std::atomic<size_t> read_pos{0};
// version stays at byte offset 16 across layout versions, so a reader
// on a mismatched file always reads a real version field instead of
// arbitrary bytes.
alignas(DESTRUCTIVE_INTERFERENCE_SIZE) std::atomic<size_t> write_pos{0};
const size_t capacity;
std::atomic<int> version{0};
int expected_version{0};
const size_t capacity;
size_t mask;
const size_t mask;
alignas(DESTRUCTIVE_INTERFERENCE_SIZE) std::atomic<size_t> read_pos{0};
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

bufferHeader(size_t size);
};
Expand All @@ -71,6 +80,9 @@ template<typename T> class sharedRingBuffer {
bufferHeader *header_;
T *data_;
size_t bufferSize_;
size_t cachedWritePos_ = 0;
size_t cachedReadPos_ = 0;
size_t cachedMask_ = 0;
};

#include "cyclic_buffer.tpp"
Expand Down
46 changes: 39 additions & 7 deletions src/utils/common/cyclic_buffer.tpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
Expand Down Expand Up @@ -50,10 +50,16 @@ template<typename T>
bool
sharedRingBuffer<T>::push(const T &item) {
size_t write_pos = header_->write_pos.load(std::memory_order_relaxed);
size_t next_write = (write_pos + 1) & header_->mask;

if (next_write == header_->read_pos.load(std::memory_order_acquire))
return false; // Buffer full
size_t next_write = (write_pos + 1) & cachedMask_;

// Don't use full(): it re-reads the consumer-owned read_pos on every call.
// The cached check only touches that line when the buffer appears full.
if (next_write == cachedReadPos_) {
cachedReadPos_ = header_->read_pos.load(std::memory_order_acquire);
if (next_write == cachedReadPos_) {
return false; // Buffer full
}
}

data_[write_pos] = item;

Expand All @@ -66,13 +72,20 @@ bool
sharedRingBuffer<T>::pop(T &item) {
size_t read_pos = header_->read_pos.load(std::memory_order_relaxed);

if (read_pos == header_->write_pos.load(std::memory_order_acquire)) return false;
// Don't use empty(): it re-reads the producer-owned write_pos on every call.
// The cached check only touches that line when the buffer appears empty.
if (read_pos == cachedWritePos_) {
cachedWritePos_ = header_->write_pos.load(std::memory_order_acquire);
if (read_pos == cachedWritePos_) {
return false;
}
}

// Read data
item = data_[read_pos];

// Update read position
size_t next_read = (read_pos + 1) & header_->mask;
size_t next_read = (read_pos + 1) & cachedMask_;
header_->read_pos.store(next_read, std::memory_order_release);
return true;
}
Expand Down Expand Up @@ -120,6 +133,15 @@ sharedRingBuffer<T>::bufferHeader::bufferHeader(size_t size) : capacity(size), m

static_assert(std::is_trivially_copyable<T>::value,
"T must be trivially copyable for shared memory");
static_assert(sizeof(bufferHeader) == 2 * DESTRUCTIVE_INTERFERENCE_SIZE,
Comment thread
ColinNV marked this conversation as resolved.
Resolved
"bufferHeader layout changed.");
static_assert(offsetof(bufferHeader, write_pos) == 0 &&
offsetof(bufferHeader, capacity) == 8 &&
offsetof(bufferHeader, version) == 16 &&
offsetof(bufferHeader, expected_version) == 20 &&
offsetof(bufferHeader, mask) == 24 &&
offsetof(bufferHeader, read_pos) == 256,
"bufferHeader field offsets changed.");
}

template<typename T>
Expand Down Expand Up @@ -170,6 +192,11 @@ sharedRingBuffer<T>::createCyclicBuffer(const std::string &name, int version) {
new (header_) bufferHeader(bufferSize_);
Comment thread
ColinNV marked this conversation as resolved.
Resolved
header_->version.store(version, std::memory_order_release);
header_->expected_version = version;

// Seed the cached values from the header
cachedWritePos_ = header_->write_pos.load(std::memory_order_acquire);
cachedReadPos_ = header_->read_pos.load(std::memory_order_acquire);
cachedMask_ = header_->mask;
Comment thread
ColinNV marked this conversation as resolved.
Resolved
}

template<typename T>
Expand Down Expand Up @@ -252,6 +279,11 @@ sharedRingBuffer<T>::openCyclicBuffer(const std::string &name, int version) {

header_ = static_cast<bufferHeader *>(ptr);
data_ = reinterpret_cast<T *>(static_cast<char *>(ptr) + sizeof(bufferHeader));

// Seed the cached values from the header
cachedWritePos_ = header_->write_pos.load(std::memory_order_acquire);
cachedReadPos_ = header_->read_pos.load(std::memory_order_acquire);
cachedMask_ = header_->mask;
}

template class sharedRingBuffer<uint8_t>;
32 changes: 31 additions & 1 deletion test/gtest/telemetry_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,36 @@ TEST_F(telemetryTest, InvalidBufferSize) {
envHelper_.popVar();
}

TEST_F(telemetryTest, ReaderReattachSeedsCachedPos) {
Comment thread
ColinNV marked this conversation as resolved.
Resolved
// Cached write and read pos need to be seeded on attach
auto path = std::string(testDir_.string()) + "/" + testFile_;
sharedRingBuffer<nixlTelemetryEvent> producer(path, true, TELEMETRY_VERSION, 8);

for (size_t i = 0; i < 3; i++) {
EXPECT_TRUE(producer.push({nixl_telemetry_event_type_t::AGENT_TX_BYTES, i}));
}
// First consumer reads part of the stream, then gets destroyed
{
sharedRingBuffer<nixlTelemetryEvent> consumer1(path, false, TELEMETRY_VERSION);
nixlTelemetryEvent out;
for (size_t i = 0; i < 2; i++) {
EXPECT_TRUE(consumer1.pop(out));
EXPECT_EQ(out.value_, i);
}
}
// A second consumer attaches mid-stream, still SPSC
{
// Must see exactly the one unread event, then empty
sharedRingBuffer<nixlTelemetryEvent> consumer2(path, false, TELEMETRY_VERSION);
nixlTelemetryEvent out;
EXPECT_EQ(consumer2.size(), 1u);
EXPECT_TRUE(consumer2.pop(out));
EXPECT_EQ(out.value_, 2u);
EXPECT_FALSE(consumer2.pop(out));
}
EXPECT_FALSE(producer.full());
}

TEST_F(telemetryTest, NonexistentExporterThrows) {
// An explicitly requested exporter that cannot be loaded must surface the
// failure rather than silently disabling telemetry.
Expand Down Expand Up @@ -273,7 +303,7 @@ TEST_F(telemetryTest, AddXferStatsRxBranch) {
TEST_F(telemetryTest, TelemetryEventStructure) {
nixlTelemetryEvent event1(nixl_telemetry_event_type_t::AGENT_TX_BYTES, 42);

EXPECT_EQ(TELEMETRY_VERSION, 4);
EXPECT_EQ(TELEMETRY_VERSION, 5);
EXPECT_EQ(sizeof(nixlTelemetryEvent), 16);
EXPECT_EQ(event1.value_, 42);
EXPECT_EQ(event1.eventType_, nixl_telemetry_event_type_t::AGENT_TX_BYTES);
Expand Down
Loading