From 3c8ca1b8367eb1107019d62636e4de5de1e63711 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:47:50 +0100
Subject: [PATCH] docs(telemetry): fix doc references to match pimpl
 architecture

Replace references to non-existent TracingInstrumentation.h with
SpanGuard.cpp pimpl implementation that actually exists on this branch.
Update conditional compilation section to describe the pimpl approach.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 OpenTelemetryPlan/OpenTelemetryPlan.md |  2 +-
 docs/build/telemetry.md                | 32 +++++++++++++-------------
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/OpenTelemetryPlan/OpenTelemetryPlan.md b/OpenTelemetryPlan/OpenTelemetryPlan.md
index d1f84e149e..562f89e7c4 100644
--- a/OpenTelemetryPlan/OpenTelemetryPlan.md
+++ b/OpenTelemetryPlan/OpenTelemetryPlan.md
@@ -161,7 +161,7 @@ C++ implementation examples are provided for the core telemetry infrastructure a
 - `Telemetry.h` - Core interface for tracer access and span creation
 - `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
+- `SpanGuard.cpp` - Pimpl implementation confining all OTel SDK types
 - Protocol Buffer extensions for trace context propagation
 - Module-specific instrumentation (RPC, Consensus, P2P, JobQueue)
 - Remaining modules (PathFinding, TxQ, Validator, etc.) follow the same patterns
diff --git a/docs/build/telemetry.md b/docs/build/telemetry.md
index 5d4ebbf0e3..e8d7fb2dd5 100644
--- a/docs/build/telemetry.md
+++ b/docs/build/telemetry.md
@@ -251,19 +251,19 @@ The Conan package provides a single umbrella target
 
 ### Key files
 
-| File                                           | Purpose                                                      |
-| ---------------------------------------------- | ------------------------------------------------------------ |
-| `include/xrpl/telemetry/Telemetry.h`           | Abstract telemetry interface and `Setup` struct              |
-| `include/xrpl/telemetry/SpanGuard.h`           | RAII span guard with `discard()` for dropping unwanted spans |
-| `include/xrpl/telemetry/DiscardFlag.h`         | Thread-local discard flag (zero-dependency header)           |
-| `src/libxrpl/telemetry/Telemetry.cpp`          | OTel SDK setup, `FilteringSpanProcessor`, provider lifecycle |
-| `src/libxrpl/telemetry/TelemetryConfig.cpp`    | Config parser (`setup_Telemetry()`)                          |
-| `src/libxrpl/telemetry/NullTelemetry.cpp`      | No-op implementation (used when disabled)                    |
-| `src/xrpld/telemetry/TracingInstrumentation.h` | Convenience macros (`XRPL_TRACE_RPC`, etc.)                  |
-| `src/xrpld/rpc/detail/ServerHandler.cpp`       | RPC entry point instrumentation                              |
-| `src/xrpld/rpc/detail/RPCHandler.cpp`          | Per-command instrumentation                                  |
-| `docker/telemetry/docker-compose.yml`          | Observability stack (Collector + Tempo + Grafana)            |
-| `docker/telemetry/otel-collector-config.yaml`  | OTel Collector pipeline configuration                        |
+| File                                          | Purpose                                                      |
+| --------------------------------------------- | ------------------------------------------------------------ |
+| `include/xrpl/telemetry/Telemetry.h`          | Abstract telemetry interface and `Setup` struct              |
+| `include/xrpl/telemetry/SpanGuard.h`          | RAII span guard with `discard()` for dropping unwanted spans |
+| `include/xrpl/telemetry/DiscardFlag.h`        | Thread-local discard flag (zero-dependency header)           |
+| `src/libxrpl/telemetry/Telemetry.cpp`         | OTel SDK setup, `FilteringSpanProcessor`, provider lifecycle |
+| `src/libxrpl/telemetry/TelemetryConfig.cpp`   | Config parser (`setup_Telemetry()`)                          |
+| `src/libxrpl/telemetry/NullTelemetry.cpp`     | No-op implementation (used when disabled)                    |
+| `src/libxrpl/telemetry/SpanGuard.cpp`         | Pimpl implementation for SpanGuard (all OTel types confined) |
+| `src/xrpld/rpc/detail/ServerHandler.cpp`      | RPC entry point instrumentation                              |
+| `src/xrpld/rpc/detail/RPCHandler.cpp`         | Per-command instrumentation                                  |
+| `docker/telemetry/docker-compose.yml`         | Observability stack (Collector + Tempo + Grafana)            |
+| `docker/telemetry/otel-collector-config.yaml` | OTel Collector pipeline configuration                        |
 
 ### Span discard mechanism
 
@@ -290,9 +290,9 @@ if (result != tesSUCCESS)
 
 ### Conditional compilation
 
-All OpenTelemetry SDK headers are guarded behind `#ifdef XRPL_ENABLE_TELEMETRY`.
-The instrumentation macros in `TracingInstrumentation.h` compile to `((void)0)` when
-the define is absent.
+All OpenTelemetry SDK types are hidden behind the pimpl idiom in `SpanGuard.cpp`.
+When `XRPL_ENABLE_TELEMETRY` is not defined, `SpanGuard.h` provides an all-inline
+no-op stub class with zero overhead and zero OTel dependencies.
 At runtime, if `enabled=0` is set in config (or the section is omitted), a
 `NullTelemetry` implementation is used that returns no-op spans.
 This two-layer approach ensures zero overhead when telemetry is not wanted.