Merge branch 'pratik/otel-phase4-consensus-tracing' into pratik/otel-phase5-docs-deployment

Brings M1 (dropped-deterministic-id counter) + M2 (childSpan doc) forward.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

include/xrpl/telemetry/DeterministicIdGenerator.h

@@ -167,6 +167,22 @@ public:
     operator=(PendingTraceId&&) = delete;
 };
 
+/**
+ * Running count of deterministic trace_ids that were pinned by a
+ * PendingTraceId but never consumed by a forced-root span before the guard was
+ * destroyed. Bumped once per silent drop.
+ *
+ * ~PendingTraceId also asserts on this condition, but the assert is a no-op in
+ * release builds, so this monotonic counter is the only signal that a
+ * deterministic trace root was lost there. It is process-wide (summed across
+ * all threads) and intended for a future diagnostic metric or debugger
+ * inspection; reading it has no side effects.
+ *
+ * @return the total number of unconsumed deterministic trace_id drops so far.
+ */
+[[nodiscard]] std::uint64_t
+unconsumedDeterministicIdDrops() noexcept;
+
 }  // namespace xrpl::telemetry
 
 #endif  // XRPL_ENABLE_TELEMETRY

include/xrpl/telemetry/SpanGuard.h

@@ -341,10 +341,19 @@ public:
     // --- Child / linked span creation ----------------------------------
 
     /**
-     * Create a child span parented to the current thread's active
-     * context. This is meaningful when this guard's span is active on
-     * the thread (e.g. wrapped in a ScopedSpanGuard); otherwise the
-     * child inherits whatever context is currently on the stack.
+     * Create a child span parented to the CURRENT ambient context of this
+     * store, not to this guard's own span. It reads the active context via the
+     * runtime context store, so it is meaningful only when a scope is active on
+     * THIS store — a ScopedSpanGuard, a ScopedActivation, or this guard's span
+     * activated some other way. With coroutine-aware storage the ambient
+     * context is the correct parent in scoped and coroutine contexts (a
+     * coroutine keeps its store across a resume on another worker). When no
+     * scope is active the child inherits whatever context happens to be on the
+     * store, which may be unrelated.
+     *
+     * For explicit, store-independent parenting to a specific span (e.g.
+     * across stores or threads), capture spanContext() and use
+     * childSpan(name, ctx) instead.
      * @param name  Span name for the child.
      * @return A new guard, or null if this guard is inactive.
      */