Guidance needed for implementing tracing API

[MobiliteDev]

I am currently implementing a simplified tracing API for my uses, aiming to abstract away the complexities of manual span management. The goal is to get a straightforward API that allows me to start traces, end traces, and add subtraces without directly dealing with parent-child span relationships.

Here's what I am trying to achieve:

• Start Trace: Initiates a new trace or a root span.

• End Trace: Closes the currently active span and automatically manages the context to revert to the parent span.

• Add Subtrace: Creates a new sub-span under the current active span.

I've encountered a challenge with the Span class, particularly in retrieving and managing the parent span when ending a trace. The current Span implementation exposes parentSpanId, but it doesn't provide direct access to the parent Span object, which is necessary to handle the thing properly.

Questions:

1. Is there an existing implementation or pattern within the library that supports this kind of API, specifically for managing the parent span relationship internally?

2. If such functionality is not currently available, is this normal because the lib is under development ? Am i missing something important ?

[blakeroberts-wk]

Some things to keep in mind:

1. The relationship between a parent and child is created by the child.
2. The relationship is created when the child span is created and it is immutable.
3. The only concrete implementation of a "trace" is the trace ID that is either created or inherited when a span is created.

With respect to the API you are trying to achieve:

• Start Trace: when starting a span, the context the span is started with needs to contain an invalid span context. Consider this code:

  opentelemetry-dart/lib/src/api/open_telemetry.dart

  Lines 76 to 79 in 008b945

  	// TODO: use start span option `newRoot` instead
  	if (newRoot) {
  	context = api.contextWithSpanContext(context, api.SpanContext.invalid());
  	}

  .
• End Trace: The best way to manage context automatically is to use zones. When execution context leaves the zone where a span is active, the span is no longer active and thus the active context "reverts" to the parent span of the parent zone, if any.
• Add Subtrace: Again, the best way to manage context automatically is zones. Consider the same code linked above.

I believe this answers your questions, loosely. I apologize for the brevity. It's hard to be succinct. I think the implementation of the linked function is the most succinct answer to your questions.

Aside: I am on the fence about the current implementation of contexts and their use of zones. I've been collecting my thoughts and would like to open an issue and fish for feedback regarding changes to the implementation. But the changes, or reasons for the changes, don't feel very well fleshed out yet. Maybe I still open the issue though. Perhaps folks such as yourself can help clear up the fog where I'm struggling!

[blakeroberts-wk]

Here's the issue I made on consolidating context APIs: #185