document pitfalls, e.g. confusion between tracer.Tracer() and tracer.tracer()

[alban]

Is your feature request related to a problem?

Yes, I initially tried the example from the README.md:

trace.set_preferred_tracer_implementation(lambda T: Tracer())
tracer = trace.tracer()
with tracer.start_span('foo'):
    print(Context)
    with tracer.start_span('bar'):
        print(Context)
        with tracer.start_span('baz'):
            print(Context)
        print(Context)
    print(Context)

But I made a typo with the casing: I typed trace.Tracer() (the constructor for the abstract class Tracer) instead of trace.tracer() (returning the preferred implementation, configurable with set_preferred_tracer_implementation()). The output ended up as the following:

AsyncRuntimeContext({'current_span': None})
AsyncRuntimeContext({'current_span': None})
AsyncRuntimeContext({'current_span': None})
AsyncRuntimeContext({'current_span': None})
AsyncRuntimeContext({'current_span': None})

After fixing the typo, the correct output is displayed:

AsyncRuntimeContext({'current_span': Span(name="foo")})
AsyncRuntimeContext({'current_span': Span(name="bar")})
AsyncRuntimeContext({'current_span': Span(name="baz")})
AsyncRuntimeContext({'current_span': Span(name="bar")})
AsyncRuntimeContext({'current_span': Span(name="foo")})

It confused me at first that there was no error message from the typo.

Describe the solution you'd like

Maybe some documentation docs/pitfalls.md with a checklist of symptoms and common mistakes.

[toumorokoshi]

Would it be better to rename of modify the API to eliminate the pitfall? Docs are good but oftentimes they are not read or missed.

[carlosalberto]

Actually for this reason (and a few others) we have global_tracer() instead of tracer() in OpenTracing. Maybe get_tracer() would be ok for us?

[toumorokoshi]

how about get_global_tracer()? I like the explicit "global" in the name.

[Oberon00]

Depending on #123, globals().tracer() sounds good.

[c24t]

This is covered now in #123.