[Doc] Number of root spans per trace

[b-viguier]

Hello 👋 🙂

This repository states that a trace can contain several root spans:

opentelemetry-proto/opentelemetry/proto/trace/v1/trace.proto

Lines 127 to 128 in 9e7c1b3

	// or more subspans for its sub-operations. A trace can also contain
	// multiple root spans, or none at all. Spans do not need to be

A trace can also contain multiple root spans, or none at all.

but the documentation repository explicitly says that a trace contains only 1 root span
https://github.com/open-telemetry/opentelemetry-specification/blob/5fb819c72e34cb21fe1ce5acba1dc93c2216ecb1/specification/trace/api.md?plain=1#L384-L386

Each trace includes a single root span, which is the shared ancestor of all other spans in the trace.

Which one is right? 😅
My feeling is that the 2nd statement is right (1 single root span per trace). But when receiving spans from the collector, it's possible to receive several root spans from different traces, in a same OTLP payload, maybe it's the source of the mistake?

[arminru]

Hey @b-viguier!

If you produce spans via the OTel Trace API, you can only specify a parent Span (via a Context) from which the Trace ID is re-used along with the parent Span ID but there is no way to specify just a Trace ID to create a root span using it. For root spans, a new, random Trace ID would be generated.
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span-creation
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#determining-the-parent-span-from-a-context

On a data model/protocol level, however, other producers would technically be able to construct multiple spans with identical Trace IDs but no Parent Span ID. The lines you are citing - for my understanding - kind of serve as warning for proto consumers that they might encounter such data and would need to gracefully handle this.

[b-viguier]

Hi @arminru, thanks for your reply!

The lines you are citing - for my understanding - kind of serve as warning for proto consumers that they might encounter such data and would need to gracefully handle this.

But in these case, we could have the same warning for every required fields?
The protocol cannot ensure all semantic constraints are respected by every SDK implementation 🤔

At least, it comforts me that in the right use-case we should have only 1 root span per trace 😅

[arminru]

@b-viguier Indeed - I don't know why this particular possible deviation is documented while others are not.
Generally I think it makes sense to have it here at least, so consumers know that "get me the span with parent_span_id=null" might not always yield exactly 1 as one would expect.

I tried to clarify the comment in #408, please let me know if this is clear enough 🙂

[b-viguier]

Your proposal is very relevant, thanks a lot 👍