Clarify the order of mutually exclusive params when creating spans.

[songy23]

Fixes #133.

The current order is local parent span -> remote parent span context -> no parent, if more than one out of the three parameters are set. Feel free to propose an alternative.

[reyang]

This seems to be language specific. Do we intend to document language specific behavior here? For Python, probably we could take a different approach, do we want to put it in the spec as well (I guess no)?

_default = object()
def start_span(tracer, name, parent=_default):
    if parent is _default:
        parent = tracer.get_current_span()
    ...

tracer.start_span('foobar')  # create a span as a child of the current span (or root span if there is no current span)
tracer.start_span('foobar', parent=parent_span)  # create a child span under span 'parent_span'
tracer.start_span('foobar', parent=None)  # create a root span
tracer.start_span('foobar', parent=ctx)  # create a span as a child of parent context

@c24t

[songy23]

Yes this PR is a bit language-specific but it's meant to reduce ambiguity in behavior. I think the approach you proposed is still consistent with the current spec, since we mentioned local parent span and remote parent span context are optional parameters so you're free to implement it with default values.

[carlosalberto]

I agree that this is language specific, but I think it's better to keep it this time like this for clarity purposes, while we figure out what other languages do.

We can refine it later ;)

[c24t]

I agree that this is oddly implementation-specific for the spec; it sounds more like a description of a specific language API. It's not clear to me that the spec should require that the start_span method should even handle all three cases.

[reyang]

LGTM, though it seems to be a bit language specific.

[iredelmeier]

Many (most?) languages allow for patterns that would let us avoid the problem solved by both this and #131 (closed too quickly to discuss there), e.g., the Python approach suggested by @reyang or an interface.

I propose that rather than focusing on workarounds, we should encourage patterns that let us avoid the problems altogether.

[SergeyKanzhelev]

I propose that rather than focusing on workarounds, we should encourage patterns that let us avoid the problems altogether.

Is this comment blocking the PR? Do you have a suggestion on how to rephrase this better?

[carlosalberto]

I propose that rather than focusing on workarounds, we should encourage patterns that let us avoid the problems altogether.

Oh, we can do that, but we need a few people from other languages to chime in and make sure one way or another sounds valid ;)

(Also, we can always change stuff later on, of course)

[SergeyKanzhelev]

I suggest to merge this as it addresses the immediate problem of describing API surface and clarifying the intent and ordering of fields. Let's iterate on this doc over time

[songy23]

I propose that rather than focusing on workarounds, we should encourage patterns that let us avoid the problems altogether.

Please file an issue for that. Though I'm afraid if we go with this approach we may end up enumerating the behavior for each language in the spec.