From ff8cf3797ae55d9d8a30f8f1bfda2ebc21f14011 Mon Sep 17 00:00:00 2001 From: Hadi Sandid Date: Thu, 5 Mar 2026 11:36:03 +0100 Subject: [PATCH] stats: add support for ring buffer type * Support for ring buffers entries in the VPP stats-segment was recently introduced (https://gerrit.fd.io/r/c/vpp/+/43471) * This PR introduces support in the statseg_v2 for consuming ring-buffer entries (config, metadata, data), and also displaying ring-buffer information when dumping through the stats-client. Signed-off-by: Hadi Sandid --- adapter/stats_api.go | 50 +++++++++ adapter/statsclient/stat_segment_api.go | 1 + adapter/statsclient/statseg_v2.go | 130 ++++++++++++++++++++++++ 3 files changed, 181 insertions(+) diff --git a/adapter/stats_api.go b/adapter/stats_api.go index bcbd4797..a8549974 100644 --- a/adapter/stats_api.go +++ b/adapter/stats_api.go @@ -67,6 +67,7 @@ const ( Symlink StatType = "Symlink" GaugeIndex StatType = "GaugeIndex" HistogramLog2 StatType = "HistogramLog2" + RingBuffer StatType = "RingBuffer" ) // StatDir defines directory of stats entries created by PrepareDir. @@ -160,6 +161,33 @@ type HistogramLog2Bin struct { // HistogramLog2Stat represents stat for a log2 histogram. The array represents workers. type HistogramLog2Stat []HistogramLog2Bin +// RingBufferConfig holds the configuration for a ring buffer. +type RingBufferConfig struct { + EntrySize uint32 + RingSize uint32 + NThreads uint32 + SchemaSize uint32 + SchemaVersion uint32 +} + +// RingBufferThreadMeta holds per-thread metadata for a ring buffer. +type RingBufferThreadMeta struct { + Head uint32 + SchemaVersion uint32 + Sequence uint64 + SchemaOffset uint32 + SchemaSize uint32 +} + +// RingBufferStat represents a snapshot of a ring buffer's configuration, per-thread metadata, +// and raw ring data. +type RingBufferStat struct { + Config RingBufferConfig + Threads []RingBufferThreadMeta + Schema []byte + Data [][]byte // per-thread raw ring data +} + func (ScalarStat) isStat() {} func (ErrorStat) isStat() {} func (SimpleCounterStat) isStat() {} @@ -168,6 +196,7 @@ func (NameStat) isStat() {} func (EmptyStat) isStat() {} func (GaugeStat) isStat() {} func (HistogramLog2Stat) isStat() {} +func (RingBufferStat) isStat() {} func (s ScalarStat) IsZero() bool { return s == 0 @@ -314,3 +343,24 @@ func (s HistogramLog2Stat) String() string { } return b.String() } + +func (s RingBufferStat) IsZero() bool { + return s.Config.NThreads == 0 || s.Config.EntrySize == 0 +} + +func (s RingBufferStat) Type() StatType { + return RingBuffer +} + +func (s RingBufferStat) String() string { + var b strings.Builder + fmt.Fprintf(&b, "\n config: entry_size=%d, ring_size=%d, threads=%d, schema_version=%d, schema_size=%d", + s.Config.EntrySize, s.Config.RingSize, s.Config.NThreads, s.Config.SchemaVersion, s.Config.SchemaSize) + + for i, t := range s.Threads { + fmt.Fprintf(&b, "\n thread[%d]: head=%d seq=%d schema_version=%d", + i, t.Head, t.Sequence, t.SchemaVersion) + } + + return b.String() +} diff --git a/adapter/statsclient/stat_segment_api.go b/adapter/statsclient/stat_segment_api.go index 7e45937e..af7ca71b 100644 --- a/adapter/statsclient/stat_segment_api.go +++ b/adapter/statsclient/stat_segment_api.go @@ -47,6 +47,7 @@ var dirTypeMapping = map[dirType]adapter.StatType{ 5: adapter.Empty, 6: adapter.Symlink, 7: adapter.HistogramLog2, + 8: adapter.RingBuffer, 9: adapter.GaugeIndex, } diff --git a/adapter/statsclient/statseg_v2.go b/adapter/statsclient/statseg_v2.go index db67ea32..98059448 100644 --- a/adapter/statsclient/statseg_v2.go +++ b/adapter/statsclient/statseg_v2.go @@ -252,6 +252,9 @@ func (ss *statSegmentV2) CopyEntryData(segment dirSegment, index uint32) adapter case adapter.GaugeIndex: return adapter.GaugeStat(dirEntry.unionData) + case adapter.RingBuffer: + return ss.copyRingBufferData(dirEntry) + default: // TODO: monitor occurrences with metrics debugf("Unknown type %d for stat entry: %q", dirEntry.directoryType, dirEntry.name) @@ -388,6 +391,14 @@ func (ss *statSegmentV2) UpdateEntryData(segment dirSegment, stat *adapter.Stat) case adapter.GaugeStat: *stat = adapter.GaugeStat(dirEntry.unionData) + case adapter.RingBufferStat: + ringBufferStat := ss.copyRingBufferData(dirEntry) + if ringBufferStat == nil { + debugf("failed to read ring buffer data for %s", dirEntry.name) + return ErrStatDataLenIncorrect + } + *stat = ringBufferStat + default: if Debug { Log.Debugf("Unrecognized stat type %T for stat entry: %v", stat, dirEntry.name) @@ -429,6 +440,125 @@ func (ss *statSegmentV2) copyHistogramLog2Data(dirEntry *statSegDirectoryEntryV2 return data } +type ringBufferHeader struct { + EntrySize uint32 + RingSize uint32 + NThreads uint32 + SchemaSize uint32 + SchemaVersion uint32 + MetadataOffset uint32 + DataOffset uint32 +} + +// Respective VPP struct vlib_stats_ring_metadata_t is padded to 64 bytes for cache alignment +const ringBufferMetaSize = 64 + +type ringBufferThreadMeta struct { + Head uint32 + SchemaVersion uint32 + Sequence uint64 + SchemaOffset uint32 + SchemaSize uint32 + _ [40]byte // padding to cache line size +} + +func (ss *statSegmentV2) copyRingBufferData(dirEntry *statSegDirectoryEntryV2) adapter.Stat { + base := ss.adjust(dirVector(&dirEntry.unionData)) + if base == nil { + debugf("ring buffer data pointer is out of range for %s", dirEntry.name) + return nil + } + + // Get start and end of ring buffer entry mapped region. + baseAddr := uintptr(unsafe.Pointer(base)) + segEnd := uintptr(unsafe.Pointer(&ss.sharedHeader[len(ss.sharedHeader)-1])) + 1 + + // Verify the ring buffer header fits within the mapped region. + headerSize := unsafe.Sizeof(ringBufferHeader{}) + if baseAddr+headerSize > segEnd { + debugf("ring buffer header extends beyond shared memory for %s", dirEntry.name) + return nil + } + + // Cast to header struct instead of reading fields individually. + header := (*ringBufferHeader)(unsafe.Pointer(base)) + + // Verify metadata region fits within the mapped region. + metaEnd := baseAddr + uintptr(header.MetadataOffset) + uintptr(header.NThreads)*ringBufferMetaSize + if metaEnd > segEnd { + debugf("ring buffer metadata extends beyond shared memory for %s (metaEnd=%d, segEnd=%d)", + dirEntry.name, metaEnd, segEnd) + return nil + } + + // Verify data region fits within the mapped region. + threadDataSize := uintptr(header.RingSize) * uintptr(header.EntrySize) + dataEnd := baseAddr + uintptr(header.DataOffset) + uintptr(header.NThreads)*threadDataSize + if dataEnd > segEnd { + debugf("ring buffer data extends beyond shared memory for %s (dataEnd=%d, segEnd=%d)", + dirEntry.name, dataEnd, segEnd) + return nil + } + + config := adapter.RingBufferConfig{ + EntrySize: header.EntrySize, + RingSize: header.RingSize, + NThreads: header.NThreads, + SchemaSize: header.SchemaSize, + SchemaVersion: header.SchemaVersion, + } + + // Read per-thread metadata by casting to the raw struct. + threads := make([]adapter.RingBufferThreadMeta, header.NThreads) + for i := uint32(0); i < header.NThreads; i++ { + meta := (*ringBufferThreadMeta)(unsafe.Pointer( + baseAddr + uintptr(header.MetadataOffset) + uintptr(i)*ringBufferMetaSize, + )) + threads[i] = adapter.RingBufferThreadMeta{ + Head: meta.Head, + SchemaVersion: meta.SchemaVersion, + Sequence: meta.Sequence, + SchemaOffset: meta.SchemaOffset, + SchemaSize: meta.SchemaSize, + } + } + + // Read schema from the first thread that has one. + var schema []byte + for _, t := range threads { + if t.SchemaSize > 0 && t.SchemaOffset > 0 { + schemaEnd := baseAddr + uintptr(t.SchemaOffset) + uintptr(t.SchemaSize) + if schemaEnd > segEnd { + debugf("ring buffer schema extends beyond shared memory for %s (schemaEnd=%d, segEnd=%d)", + dirEntry.name, schemaEnd, segEnd) + continue + } + schemaPtr := unsafe.Pointer(baseAddr + uintptr(t.SchemaOffset)) + srcSchema := unsafe.Slice((*byte)(schemaPtr), t.SchemaSize) + schema = make([]byte, t.SchemaSize) + copy(schema, srcSchema) + break + } + } + + // Copy per-thread raw ring data. + data := make([][]byte, header.NThreads) + for i := uint32(0); i < header.NThreads; i++ { + srcPtr := unsafe.Pointer(baseAddr + uintptr(header.DataOffset) + uintptr(i)*threadDataSize) + srcSlice := unsafe.Slice((*byte)(srcPtr), threadDataSize) + threadData := make([]byte, threadDataSize) + copy(threadData, srcSlice) + data[i] = threadData + } + + return adapter.RingBufferStat{ + Config: config, + Threads: threads, + Schema: schema, + Data: data, + } +} + // Adjust data pointer using shared header and base and return // the pointer to a data segment func (ss *statSegmentV2) adjust(data dirVector) dirVector {