Removing create_span from the api

[codeboten]

Simplifying the API by removing create_span. Updated the WSGI integration and docs.

Resolves #152

Signed-off-by: Alex Boten aboten@lightstep.com

[codecov-io]

Codecov Report

Merging #290 into master will decrease coverage by 0.11%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #290      +/-   ##
==========================================
- Coverage   85.66%   85.55%   -0.12%     
==========================================
  Files          33       33              
  Lines        1612     1599      -13     
  Branches      180      178       -2     
==========================================
- Hits         1381     1368      -13     
  Misses        185      185              
  Partials       46       46

Impacted Files	Coverage Δ
...ntelemetry-api/src/opentelemetry/trace/__init__.py	85.95% <ø> (-0.34%)	⬇️
...emetry-sdk/src/opentelemetry/sdk/trace/__init__.py	88.94% <100%> (-0.18%)	⬇️
...ry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py	90.54% <100%> (-0.37%)	⬇️
...src/opentelemetry/ext/opentracing_shim/__init__.py	95.83% <100%> (-0.14%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update da8b8d9...371fa89. Read the comment docs.

[Oberon00]

From #206 (comment):

This PR must not remove the capability of specifying explicit start times for the span. This is both in the spec and was explicitly requested, see #134. I guess the parameter should be added to start_span at least.

[Oberon00]

I would remove this paragraph, and maybe also rename the method to _create_span. Or we could commit to having this method be a "semi-public" interface of the SDK, to be overriden by any vendor-SDKs that need their own Span type but nevertheless want to reuse functionality from vendor SDKs.

In any case, applications (or any instrumentation use case really) must not use this method.

[Oberon00]

We should also remove span.start() from the public API. We can either move the code to Tracer.start_span or just remove the method from the API but keep it in the SDK (preferably renaming it to _start).

[codeboten]

Would love some feedback on whether or not this is the right thing to do here, since a DefaultSpan no longer has a start() method, I'm just returning it after creation

[Oberon00]

I think this is fine, a DefaultSpan doesn't even know whether it was started anyway.

[Oberon00]

@open-telemetry/python-approvers: We need more reviews for this one!

[c24t]

Changes LGTM, FYI I pushed some conflict fixes after merging #206.

[c24t]

In 371fa89 I changed some tests that relied on the fact that start_span and others called create_span and start under the hood. These changes make the tests more brittle since they're checking for a specific call now (start_span) instead of checking that the span was created.

Also note that because start has been moved to the SDK, there's no way to tell that a span has been started if it's an API object mock.

[Oberon00]

@c24t about the test issues: I think we should switch all ext tests to use the SDK and the in-memory exporter instead of unittest.mock. That way the tests should be both easier to write & understand and test something that is closer to reality.

I created #303 to track this, I think we should do this in a separate PR, and I still think this one is fine.