From 7bdc14eee5d2843a3fc11eb00e5f9f15f9c608a5 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Wed, 22 Jul 2026 10:58:35 +0100
Subject: [PATCH] =?UTF-8?q?docs(telemetry):=2009-doc=20=E2=80=94=20determi?=
 =?UTF-8?q?nistic=20roots=20are=20true=20roots;=20rootSpan->freshRoot?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document that deterministic-trace_id spans (tx.* apply pipeline, tx.process,
tx.receive, consensus.round) are now genuine trace roots with empty
parent_span_id via the custom DeterministicIdGenerator, superseding the old
synthetic-parent behavior that showed 'root span not yet received' in Tempo.
Also update the fresh-root note: peer entry spans use ScopedSpanGuard::freshRoot().

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 OpenTelemetryPlan/09-data-collection-reference.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md
index d911cf88ff..710a5a4d17 100644
--- a/OpenTelemetryPlan/09-data-collection-reference.md
+++ b/OpenTelemetryPlan/09-data-collection-reference.md
@@ -117,6 +117,14 @@ under a single trace even though they run sequentially and often on different
 threads. A transaction that hard-fails preflight or preclaim never reaches the
 later spans — the `stage` attribute identifies where it stopped.
 
+> **Deterministic roots are true roots.** Spans with a deterministic `trace_id`
+> (the `tx.*` apply pipeline, `tx.process`, `tx.receive`, and `consensus.round`)
+> are emitted as genuine trace roots with an empty `parent_span_id`. The chosen
+> `trace_id` is injected through a custom `DeterministicIdGenerator` on the SDK's
+> no-parent branch, so there is no synthetic placeholder parent — Tempo shows a
+> clean root, not a "root span not yet received" warning. Cross-node correlation
+> still works because every node derives the same `trace_id` from the shared hash.
+
 **Where to find**: Tempo → TraceQL: `{resource.service.name="xrpld" && name=~"tx.process|tx.receive"}`
 or, for the apply pipeline: `{resource.service.name="xrpld" && name=~"tx.preflight|tx.preclaim|tx.transactor"}`
 
@@ -212,7 +220,7 @@ Controlled by `trace_peer` in `[telemetry]` config. **Enabled by default** (high
 | `peer.validation.receive` | —      | PeerImp.cpp | Validation message received from peer |
 
 A `—` parent means the span is a fresh trace root (`kConsumer`): it is started
-via `SpanGuard::rootSpan()` at the inbound-message entry point and never
+via `ScopedSpanGuard::freshRoot()` at the inbound-message entry point and never
 inherits an ambient span left active on the peer thread, so it does not nest
 under an unrelated transaction's trace.