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

# Conflicts:
#	include/xrpl/telemetry/SpanGuard.h
#	src/xrpld/overlay/detail/PeerImp.cpp

include/xrpl/telemetry/SpanGuard.h

@@ -20,6 +20,7 @@
         | + hashSpan(cat, name, hash)            [static] |
         | + hashSpan(cat, name, hash, parent)    [static] |
         | + captureContext() : SpanContext                 |
+        | + getTraceBytes() : TraceBytes                   |
         | + setAttribute(key, value)                      |
         | + setOk() / setError(desc)                      |
         | + addEvent(name)                                |
@@ -116,6 +117,7 @@
       exposed — all interaction goes through the public methods.
 */
 
+#include <array>
 #include <cstdint>
 #include <exception>
 #include <initializer_list>
@@ -133,6 +135,26 @@ namespace xrpl::telemetry {
 */
 enum class TraceCategory { Rpc, Transactions, Consensus, Peer, Ledger };
 
+/** Raw trace context bytes for cross-node propagation.
+
+    Holds the binary trace_id, span_id, and trace_flags extracted from
+    an active span. Used by protocol-layer code to inject trace context
+    into outgoing protobuf messages without depending on OTel types.
+
+    @see SpanGuard::getTraceBytes(), TraceContextPropagator.h
+*/
+struct TraceBytes
+{
+    /// 16-byte W3C trace identifier.
+    std::array<std::uint8_t, 16> traceId{};
+    /// 8-byte span identifier of the current span.
+    std::array<std::uint8_t, 8> spanId{};
+    /// W3C trace flags (bit 0 = sampled).
+    std::uint8_t traceFlags{0};
+    /// True if this struct contains valid data from an active span.
+    bool valid{false};
+};
+
 /** Key-value pair for span event attributes.
     Used by addEvent(name, attrs) to attach structured metadata to events.
 */
@@ -295,6 +317,18 @@ public:
     [[nodiscard]] SpanContext
     captureContext() const;
 
+    /** Extract raw trace context bytes from this span for propagation.
+
+        Unlike captureContext() which captures the thread-local runtime
+        context, this method reads the span's own SpanContext directly.
+        Safe to call from any thread that holds a reference to this guard.
+
+        @return A TraceBytes struct with valid=true if the span is active
+                and has a valid context, or valid=false otherwise.
+    */
+    [[nodiscard]] TraceBytes
+    getTraceBytes() const;
+
     // --- Attribute setters (explicit overloads, no OTel types) ---------
 
     /** Set a string attribute. No-op on a null guard. */
@@ -431,6 +465,11 @@ public:
     {
         return {};
     }
+    [[nodiscard]] TraceBytes
+    getTraceBytes() const
+    {
+        return {};
+    }
     // NOLINTEND(readability-convert-member-functions-to-static)
 
     void

include/xrpl/telemetry/TraceContextPropagator.h

@@ -4,8 +4,14 @@
 
     Provides serialization/deserialization of OTel trace context to/from
     Protocol Buffer TraceContext messages (P2P cross-node propagation).
+    Wired into the P2P message flow via PropagationHelpers.h for
+    TMTransaction, TMProposeSet, and TMValidation messages.
 
     Only compiled when XRPL_ENABLE_TELEMETRY is defined.
+
+    @see PropagationHelpers.h (high-level inject helpers),
+         TxTracing.h (transaction receive-side extraction),
+         ConsensusReceiveTracing.h (proposal/validation receive-side).
 */
 
 #ifdef XRPL_ENABLE_TELEMETRY