Merge branch 'pratik/otel-phase3-tx-tracing' into pratik/otel-phase4-consensus-tracing

Conflict in src/libxrpl/telemetry/SpanGuard.cpp: both sides added a different
include in the same alphabetical slot — phase-4 added <initializer_list>, the
incoming std::format change added <format>. Both are required, so both are
kept in sorted order.

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
 
 <div align="center">

src/libxrpl/telemetry/SpanGuard.cpp

@@ -57,6 +57,7 @@
 #include <cstdint>
 #include <cstring>
 #include <exception>
+#include <format>
 #include <initializer_list>
 #include <memory>
 #include <optional>
@@ -198,6 +199,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<std::string>
+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
@@ -206,10 +235,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<Impl>(tel->startSpan(fullName, categoryToSpanKind(cat))));
+    auto const fullName = joinSpanName(prefix, name);
+    if (!fullName)
+        return {};
+    return SpanGuard(std::make_unique<Impl>(tel->startSpan(*fullName, categoryToSpanKind(cat))));
 }
 
 SpanGuard
@@ -218,13 +247,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<Impl>(tel->startSpan(fullName, rootCtx, categoryToSpanKind(cat))));
+        std::make_unique<Impl>(tel->startSpan(*fullName, rootCtx, categoryToSpanKind(cat))));
 }
 
 // ===== Child / linked span creation ========================================