Guidance around using OTel for tracing in language SDKs

[cartermp]

Something that's come up a few times in feedback channels for me was that it can be unclear which part of the API to use for which scenario.

For example, consider the following API usages in .NET:

using var span1 = tracer.StartSpan("one");

//...

using var span2 = tracer.StartActiveSpan("two");

and in Java:

Span span1 = tracer.spanBuilder("parent").startSpan();

//...

Span span2 = tracer.spanBuilder("parent").startSpan();
span2.makeCurrent();

Which is the "right" thing to do? Well, if you dig through some issues, you'll stumble on this comment: open-telemetry/opentelemetry-specification#469 (comment)

Couple examples wehn you need to start but not active the span:

• In case when you starting multiple async operations - you don't want to set any one of them as active on the current thread. So you pass the started span as an argument to the async callback to set as active there.
• When you want to save on tls operations and/or have custom thread pool managing logic.

Really great advice here. And the unwritten, implicit guidance here is:

you're mostly likely going to want to use StartActiveSpan for anything other than specialized scenarios like this.

In the Java docs there is this statement:

The OpenTelemetry API offers also an automated way to propagate the parent span on the current thread:

This is factual, but the question in my mind is: "Okay, but which approach should I generally use?"

Guidance will differ from language to language because their SDKs have different patterns. But I think this will be critical to document for OTel to succeed in the long term.

What other kinds of guidance can be written for language SDKs?

Some I can think of:

• Recommended way to create spans in a trace, including child/nested spans
• Recommended way to store metadata in a trace (set attributes on spans vs. store in baggage and propagate, write a span processor, etc?)
• Recommended way to configure an exporter if applicable (this tripped me up in go before)
• Recommended way to wire up automatic instrumentation (always use it? turn on as much as possible? etc.)
• Recommended approaches to sampling data based on that data (I imagine this could get punted for now)
• How to name tracer/span/attributes/baggage

[ericsampson]

In general, this section of the OTel .NET documentation (which relates to what Philip mentioned) is sorely lacking. It would be very helpful for end users if it was expanded to be as comprehensive as the surrounding sections regarding how to use this library with the native .NET Activity methods.

[cartermp]

From open-telemetry/opentelemetry-go#2481

This is probably most relevant to Go (it certainly isn't much of a concern in .NET), but there's guidance that can be offered around:

• How you should generally initialize things
• Managing things like a TracerProvider
• How many tracers per app/service? Is this scenario-based? What's the 90% case? Or is that a 99% case? etc.

[cartermp]

Another one: https://cloud-native.slack.com/archives/CJFCJHG4Q/p1643212043135500?thread_ts=1643187503.132000&cid=CJFCJHG4Q

This is for span status: "Don't set OK unless you're overriding ERROR"

[eugeniyk]

Thank you for adding such guidance
Personally, during migration our custom sdk based on opentracing API /Jaeger SDK (java) to opentelemetry API / SDK I found few additional topics not clear from the first sight:

Meta concerns:

• shift in mindset (before span controlled tags and baggage, now it's all about context)
• [java] unification of scoping: Baggage.current / Span.current is part of Context

Unit testing practices:

• how it's intended to be setup, in code and tests?
• how to force span flushing if you're using BatchSpanProcessor. (If you don't have access to SdkSpanProcessor, you can't cast since it's obfuscated..)
• how to test not-yet-reported spans? there is no MockSpan or SpanData available, so you have to end the span first and only then you're able to check name or list of attributes