Add documentation on how to remove the span and disable implicit child spans for a particular code path

[anuraaga]

Currently, the best way to how to remove the span and disable implicit child spans for a particular code path is probably this

try (Scope ignored = TracingContextUtils.currentContextWith(DefaultSpan.getInvalid())) {
  // Since scoped span is invalid, no tracing happens.
}

This should be documented, possibly with a helper somewhere, something like Scope withTracingDisabled().

/cc @marcingrzejszczak

[Oberon00]

Your code snippet just clears the current span, I don't know if that counts as "disable tracing". For disabling tracing, a spec issue is open at open-telemetry/opentelemetry-specification#530. EDIT: I think here you just want to clear the active span, so please be careful with terminology 😃

[anuraaga]

@Oberon00 I'm trying to differentiate between only clearing the active span, meaning a new span could be made, or making sure no new spans are made within that scope of code. Unless someone explicitly brings in a valid span with something like TracingContextUtils.currentContextWith(tracer.spanBuilder().setParent(validParent).start()), I think this does basically "disable tracing", no?

Edit: Parent would also need to be explicit to re-enable tracing

[Oberon00]

Tracing is enabled, everything works as expected, there is just no current span. For example, if you set an attribute, you would usually not do it on the return value of getCurrentSpan, but on some span object you already have, which would still work. So I am against calling this "disable tracing". Also, it would easily be confused with what open-telemetry/opentelemetry-specification#530 wants to specify.

[Oberon00]

If your code snippet disables tracing, then tracing is always initially disabled in opentelemetry-java.

[anuraaga]

Well - changed the title to be more explicit, but IMO less clear. The difference between disable and stop tracing in my mind I think is

Disabled: No spans are generated, nothing is propagated
Stopped: No spans are generated, but current span is still propagated

At least I think that's what open-telemetry/opentelemetry-specification#530 says.

As you say, the extractors have the power to set the current span, but that's about it, and happens before user code so if a user sets the Scope to an invalid Span, I'd still say tracing's disabled for all intents and purposes :P

[Oberon00]

I think there was no intention to introduce a difference between disabling and stopping tracing.

As you say, the extractors have the power to set the current span, but that's about it, and happens before user code so if a user sets the Scope to an invalid Span, I'd still say tracing's disabled for all intents and purposes :P

Why only extractors? If the user

• Starts a span like usual, it will work as usual (it will be a root span, as the parent was cleared)
• Sets any, also previously started, span as active, e.g. using Tracer.withSpan, it will work as usual.

Note that while the invalid span has sampled=false, this is ignored due to it being invalid.

[anuraaga]

Starts a span like usual, it will work as usual (it will be a root span, as the parent was cleared)

You mean using setNoParent? Yeah I guess that's true, but it's really rare to use that. I think in documentation we can refer to this as disabling "implicit tracing" - normal operations that instrument based on the current span will be no-op because the current span is invalid. We can mention it can still be explicitly overridden by a non-parented span, or a span from an unrelated ancestor - these are pretty rare cases and can be called out as exceptions I think.

[Oberon00]

You mean using setNoParent

No, also using the implicit current span as parent. EDIT: See also #1690

[anuraaga]

Ah oops - thanks yeah forgot the non-default tracer does that. It's related to that spec PR indeed.

[marcingrzejszczak]

Yeah, I'd assume that were talking about removing the span from scope. That means that if I call tracer.currentSpan() I will get a null.

[Oberon00]

currentSpan will never return null, but an invalid span if there is no current span. This is so that you never have to check if for null and calling anything on it is a no-op instead of crashing.

[jkwatson]

@anuraaga do you think this is still needed, or is this blocked on spec changes?