From 49f9fe52acebbed02e7152d028383535e8734f09 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Thu, 16 Apr 2026 17:46:03 +0100
Subject: [PATCH] docs(telemetry): update plan docs for FilteringSpanProcessor
 and discard()

Add DiscardFlag.h and FilteringSpanProcessor references to the file
tree, key files table, and implementation summary in OpenTelemetryPlan.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../03-implementation-strategy.md             | 24 ++++++++++---------
 OpenTelemetryPlan/OpenTelemetryPlan.md        |  5 ++--
 2 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/OpenTelemetryPlan/03-implementation-strategy.md b/OpenTelemetryPlan/03-implementation-strategy.md
index 8e9311639d..f607ef5f3b 100644
--- a/OpenTelemetryPlan/03-implementation-strategy.md
+++ b/OpenTelemetryPlan/03-implementation-strategy.md
@@ -15,12 +15,13 @@ include/xrpl/
 │   ├── Telemetry.h              # Main telemetry interface
 │   ├── TelemetryConfig.h        # Configuration structures
 │   ├── TraceContext.h           # Context propagation utilities
-│   ├── SpanGuard.h              # RAII span management
+│   ├── SpanGuard.h              # RAII span management with discard()
+│   ├── DiscardFlag.h            # Thread-local discard flag
 │   └── SpanAttributes.h         # Attribute helper functions
 
 src/libxrpl/
 ├── telemetry/
-│   ├── Telemetry.cpp            # Implementation
+│   ├── Telemetry.cpp            # Implementation + FilteringSpanProcessor
 │   ├── TelemetryConfig.cpp      # Config parsing
 │   ├── TraceContext.cpp         # Context serialization
 │   └── NullTelemetry.cpp        # No-op implementation
@@ -380,15 +381,16 @@ pie title Code Changes by Component
 
 #### New Files (No Impact on Existing Code)
 
-| File                                           | Lines | Purpose              |
-| ---------------------------------------------- | ----- | -------------------- |
-| `include/xrpl/telemetry/Telemetry.h`           | ~160  | Main interface       |
-| `include/xrpl/telemetry/SpanGuard.h`           | ~120  | RAII wrapper         |
-| `include/xrpl/telemetry/TraceContext.h`        | ~80   | Context propagation  |
-| `src/xrpld/telemetry/TracingInstrumentation.h` | ~60   | Macros               |
-| `src/libxrpl/telemetry/Telemetry.cpp`          | ~200  | Implementation       |
-| `src/libxrpl/telemetry/TelemetryConfig.cpp`    | ~60   | Config parsing       |
-| `src/libxrpl/telemetry/NullTelemetry.cpp`      | ~40   | No-op implementation |
+| File                                           | Lines | Purpose                                 |
+| ---------------------------------------------- | ----- | --------------------------------------- |
+| `include/xrpl/telemetry/Telemetry.h`           | ~160  | Main interface                          |
+| `include/xrpl/telemetry/SpanGuard.h`           | ~120  | RAII wrapper + discard                  |
+| `include/xrpl/telemetry/DiscardFlag.h`         | ~28   | Thread-local discard flag               |
+| `include/xrpl/telemetry/TraceContext.h`        | ~80   | Context propagation                     |
+| `src/xrpld/telemetry/TracingInstrumentation.h` | ~60   | Macros                                  |
+| `src/libxrpl/telemetry/Telemetry.cpp`          | ~400  | Implementation + FilteringSpanProcessor |
+| `src/libxrpl/telemetry/TelemetryConfig.cpp`    | ~60   | Config parsing                          |
+| `src/libxrpl/telemetry/NullTelemetry.cpp`      | ~40   | No-op implementation                    |
 
 #### Modified Files (Existing Rippled Code)
 
diff --git a/OpenTelemetryPlan/OpenTelemetryPlan.md b/OpenTelemetryPlan/OpenTelemetryPlan.md
index fb9f037c00..d1f84e149e 100644
--- a/OpenTelemetryPlan/OpenTelemetryPlan.md
+++ b/OpenTelemetryPlan/OpenTelemetryPlan.md
@@ -146,7 +146,7 @@ Span naming follows a hierarchical `<component>.<operation>` convention (e.g., `
 
 ## 3. Implementation Strategy
 
-The telemetry code is organized under `include/xrpl/telemetry/` for headers and `src/libxrpl/telemetry/` for implementation. Key principles include RAII-based span management via `SpanGuard`, conditional compilation with `XRPL_ENABLE_TELEMETRY`, and minimal runtime overhead through batch processing and efficient sampling.
+The telemetry code is organized under `include/xrpl/telemetry/` for headers and `src/libxrpl/telemetry/` for implementation. Key principles include RAII-based span management via `SpanGuard` (with `discard()` for dropping unwanted spans), a `FilteringSpanProcessor` that intercepts `OnEnd()` to prevent discarded spans from entering the export pipeline, conditional compilation with `XRPL_ENABLE_TELEMETRY`, and minimal runtime overhead through batch processing and efficient sampling.
 
 Performance optimization strategies include probabilistic head sampling (10% default), tail-based sampling at the collector for errors and slow traces, batch export to reduce network overhead, and conditional instrumentation that compiles to no-ops when disabled.
 
@@ -159,7 +159,8 @@ Performance optimization strategies include probabilistic head sampling (10% def
 C++ implementation examples are provided for the core telemetry infrastructure and key modules:
 
 - `Telemetry.h` - Core interface for tracer access and span creation
-- `SpanGuard.h` - RAII wrapper for automatic span lifecycle management
+- `SpanGuard.h` - RAII wrapper for automatic span lifecycle management with `discard()` support
+- `DiscardFlag.h` - Thread-local flag for span discard signaling between SpanGuard and FilteringSpanProcessor
 - `TracingInstrumentation.h` - Macros for conditional instrumentation
 - Protocol Buffer extensions for trace context propagation
 - Module-specific instrumentation (RPC, Consensus, P2P, JobQueue)