diff --git a/OpenTelemetryPlan/03-implementation-strategy.md b/OpenTelemetryPlan/03-implementation-strategy.md index 922d3d4999..f11af7a929 100644 --- a/OpenTelemetryPlan/03-implementation-strategy.md +++ b/OpenTelemetryPlan/03-implementation-strategy.md @@ -335,78 +335,6 @@ Instrumentation is gated on two levels. A compile-time feature flag (`XRPL_ENABL This section provides a detailed assessment of how intrusive the OpenTelemetry integration is to the existing xrpld codebase. -### 3.9.1 Files Modified Summary - -| Component | Files Modified | Architectural Impact | -| --------------------- | -------------- | -------------------- | -| **Core Telemetry** | 10 new files | None (new module) | -| **Application Init** | 2 files | Minimal | -| **RPC Layer** | 3 files | Minimal | -| **Transaction Relay** | 4 files | Low | -| **Consensus** | 3 files | Low-Medium | -| **Protocol Buffers** | 1 file | Low | -| **CMake/Build** | 3 files | Minimal | -| **PathFinding** | 2 | Minimal | -| **TxQ/Fee** | 2 | Minimal | -| **Validator/Amend** | 3 | Minimal | -| **Total** | **~33 files** | **Low** | - -### 3.9.2 Detailed File Impact - -```mermaid -pie title Code Changes by Component - "New Telemetry Module" : 800 - "Transaction Relay" : 160 - "Consensus" : 130 - "RPC Layer" : 100 - "PathFinding" : 80 - "TxQ/Fee" : 60 - "Validator/Amendment" : 40 - "Application Init" : 35 - "Protocol Buffers" : 25 - "Build System" : 60 -``` - -#### New Files (No Impact on Existing Code) - -| File | Purpose | -| ------------------------------------------- | ------------------------- | -| `include/xrpl/telemetry/Telemetry.h` | Main interface | -| `include/xrpl/telemetry/TelemetryConfig.h` | Configuration structures | -| `include/xrpl/telemetry/TraceContext.h` | Context propagation | -| `include/xrpl/telemetry/SpanGuard.h` | RAII wrapper | -| `include/xrpl/telemetry/DiscardFlag.h` | Thread-local discard flag | -| `include/xrpl/telemetry/SpanAttributes.h` | Attribute helpers | -| `src/libxrpl/telemetry/Telemetry.cpp` | Implementation | -| `src/libxrpl/telemetry/TelemetryConfig.cpp` | Config parsing | -| `src/libxrpl/telemetry/TraceContext.cpp` | Context serialization | -| `src/libxrpl/telemetry/NullTelemetry.cpp` | No-op implementation | - -#### Modified Files (Existing Xrpld Code) - -| File | Risk Level | -| ------------------------------------------------- | ---------- | -| `src/xrpld/app/main/Application.cpp` | Low | -| `include/xrpl/core/ServiceRegistry.h` | Low | -| `src/xrpld/rpc/detail/ServerHandler.cpp` | Low | -| `src/xrpld/rpc/handlers/*.cpp` | Low | -| `src/xrpld/overlay/detail/PeerImp.cpp` | Medium | -| `src/xrpld/overlay/detail/OverlayImpl.cpp` | Medium | -| `src/xrpld/app/consensus/RCLConsensus.cpp` | Medium | -| `src/xrpld/app/consensus/RCLConsensusAdaptor.cpp` | Medium | -| `src/xrpld/core/JobQueue.cpp` | Low | -| `src/xrpld/app/paths/PathRequest.cpp` | Low | -| `src/xrpld/app/paths/Pathfinder.cpp` | Low | -| `src/xrpld/app/misc/TxQ.cpp` | Low | -| `src/xrpld/app/main/LoadManager.cpp` | Low | -| `src/xrpld/app/misc/ValidatorList.cpp` | Low | -| `src/xrpld/app/misc/AmendmentTable.cpp` | Low | -| `src/xrpld/app/misc/Manifest.cpp` | Low | -| `src/xrpld/shamap/SHAMap.cpp` | Low | -| `src/xrpld/overlay/detail/ripple.proto` | Low | -| `CMakeLists.txt` | Low | -| `cmake/FindOpenTelemetry.cmake` | None (new) | - ### 3.9.3 Risk Assessment by Component
diff --git a/src/libxrpl/telemetry/SpanGuard.cpp b/src/libxrpl/telemetry/SpanGuard.cpp index c744fb7530..52be7ad560 100644 --- a/src/libxrpl/telemetry/SpanGuard.cpp +++ b/src/libxrpl/telemetry/SpanGuard.cpp @@ -56,6 +56,7 @@ #include #include #include +#include #include #include #include @@ -195,6 +196,34 @@ categoryToSpanKind(TraceCategory cat) return otel_trace::SpanKind::kInternal; // unreachable } +/** + * Join a span-name prefix and suffix into the dotted full name. + * + * Wraps std::format because the callers are noexcept: std::format can throw + * (std::bad_alloc, or std::format_error on a malformed spec) and an escaping + * exception would terminate the process. Telemetry must never take the node + * down, so a failure yields std::nullopt and the caller returns a null guard — + * the same degrade-to-no-op path already used when telemetry is disabled. + * + * @param prefix Segment before the dot (e.g. "consensus"). + * @param name Segment after the dot (e.g. "round"). + * @return The joined name, or std::nullopt if formatting failed. + */ +[[nodiscard]] std::optional +joinSpanName(std::string_view prefix, std::string_view name) noexcept +{ + try + { + return std::format("{}.{}", prefix, name); + } + catch (std::exception const&) + { + // Out of memory or a bad format spec. Drop the span rather than + // propagate out of a noexcept factory. + return std::nullopt; + } +} + } // namespace SpanGuard @@ -203,10 +232,10 @@ SpanGuard::span(TraceCategory cat, std::string_view prefix, std::string_view nam auto* tel = Telemetry::getInstance(); if ((tel == nullptr) || !tel->isEnabled() || !isCategoryEnabled(*tel, cat)) return {}; - std::string fullName; - fullName.reserve(prefix.size() + 1 + name.size()); - fullName.append(prefix).append(1, '.').append(name); - return SpanGuard(std::make_unique(tel->startSpan(fullName, categoryToSpanKind(cat)))); + auto const fullName = joinSpanName(prefix, name); + if (!fullName) + return {}; + return SpanGuard(std::make_unique(tel->startSpan(*fullName, categoryToSpanKind(cat)))); } SpanGuard @@ -215,13 +244,13 @@ SpanGuard::freshRoot(TraceCategory cat, std::string_view prefix, std::string_vie auto* tel = Telemetry::getInstance(); if ((tel == nullptr) || !tel->isEnabled() || !isCategoryEnabled(*tel, cat)) return {}; - std::string fullName; - fullName.reserve(prefix.size() + 1 + name.size()); - fullName.append(prefix).append(1, '.').append(name); + auto const fullName = joinSpanName(prefix, name); + if (!fullName) + return {}; // Force a fresh trace root: do NOT inherit this thread's active span. auto rootCtx = opentelemetry::context::Context{otel_trace::kIsRootSpanKey, true}; return SpanGuard( - std::make_unique(tel->startSpan(fullName, rootCtx, categoryToSpanKind(cat)))); + std::make_unique(tel->startSpan(*fullName, rootCtx, categoryToSpanKind(cat)))); } // ===== Child / linked span creation ========================================