Differences in Starting Spans

[Shackelford-Arden]

The other day I was working with a team mate on instrumenting some code and I noticed that he was using start_as_current_span() as opposed to start_span(). I noticed in the Cookbook that it refers folks to use the start_as_current_span() as well. I don't know where or why, but up until this moment, I'd never used start_as_current_span() and have been able to handle things just dandy.

So, my question is:

Why use one over the other?

In looking at the docstrings for both, they sound more or less the same to me.

In the docstring for start_as_current_span() I see the following example:

with tracer.start_as_current_span("one") as parent:
    parent.add_event("parent's event")
    with trace.start_as_current_span("two") as child:
        child.add_event("child's event")
        trace.get_current_span()  # returns child
    trace.get_current_span()      # returns parent
trace.get_current_span()          # returns previously active span

Is there any particular reason we would need to use start_as_current_span for the child span as opposed to start_span?

Thanks!

[srikanthccv]

https://opentelemetry-python.readthedocs.io/en/latest/api/trace.html#opentelemetry.trace.Tracer.start_span

Starts a span.

Create a new span. Start the span without setting it as the current span in the context. To start the span and use the context in a single method, see start_as_current_span().

By default the current span in the context will be used as parent, but an explicit context can also be specified, by passing in a Context containing a current Span. If there is no current span in the global Context or in the specified context, the created span will be a root span.

The span can be used as a context manager. On exiting the context manager, the span’s end() method will be called.

https://opentelemetry-python.readthedocs.io/en/latest/api/trace.html#opentelemetry.trace.Tracer.start_as_current_span

[Shackelford-Arden]

Since I'd already read the docstrings, this hasn't added any additional clarity for me.

Is there a particular piece to this that you're seeing that gives a clear differentiation in terms of when you would use one over the other?

edit: spelling

[srikanthccv]

Start the span without setting it as the current span in the context.

Does this not make it clear? That's the main differentiation between both. One just starts the span and other also sets as a current span in the context (without this there won't be parent/child relationship). Are you asking for a code example?

[Shackelford-Arden]

Sorry, it's just taking a bit longer to sink in for me for some reason today :)