Implementations MUST NOT allow callers to create Spans directly

[codeboten]

To be compliant with the tracing spec, implementations MUST NOT allow callers to create Spans directly

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span

[owais]

Do we provide any APIs other than the tracer to create spans currently? I'd be nice to point that out for anyone taking this on as the first issue.

[ahlaw]

Hi, can I take this issue?

[ahlaw]

I believe the most Pythonic way would be to simply document that the caller does not instantiate Spans themselves and have them face the consequences of breaking the trust rather than strictly enforcing it in this case. The sdk Span already documents this. We could also add this to the Span api docstring or just close this issue outright?

[lzchen]

@ahlaw
Perhaps we can use something like this to enforce it.

[ahlaw]

Hmm it won't strictly enforce it, but it would definitely make it almost impossible to unintentionally instantiate Span directly. Sounds good to me.

[lzchen]

Looking at the implementation now, I'm wondering if we would have to add this for all classes that we'd expect to instantiate via the api rather than directly the constructor (all classes in metrics pretty much). Would it be worth it to do all that or should we simply go with the documentation route?

Thoughts? @codeboten @aabmass

[aabmass]

I just want to raise another alternative of using Python "private" underscores (which is essentially documentation) to tell the user not to instantiate directly, but still allow easily overriding this for our testing purposes. For type annotations, we can expose a NewType

# opentelemetry/sdk/trace/__init__.py

from typing import NewType

# make it "private"
class _Span(trace_api.Span):
    # everything the same as before
    # ...
    pass

# "public" API for typing purposes
Span = NewType('Span', _Span)

class Tracer(trace_api.Tracer):
    def start_span(self, ...) -> Span:
        # .. same as before except
        return Span(_Span(...))

A user trying to call Span(name, ...) won't work (typing-wise or at runtime) and if the user really wants to override this, they'll have to use _Span which I think most python users know to use at your own risk. Thoughts?