Moving active span interaction To Trace Context Utilities (#923)

* Moving active span interaction To TracerProvider

Fixes #455.

The previous spec stated that the active span get / set behavior MUST
behave the same across Tracers retrieved from the same TracerProvider.
As such, the active span manipulation methods are better provided by the
TracerProvider directly.

As it is still cumbersome to retrieve the current TracerProvider simply
to get the current span, add in the concept of a "Trace Package", that can
provide utilty methods to delegate to the configured default TracerProvider.
This enables a fluid interface to retrieve the current span:

    from opentelemetry import trace

    current_span = trace.get_current_span()

To help maintain backwards compatibility, the Tracer may still expose
active span methods.

* Adding missing entries for TracerProvider functionality

* Addressing feedback

* fixing lint (multiple blank lines)

* Addressing feedback

Removing the get / set current span methods from the TracerProvider.

There is consensus that the functions should have the same behavior
regardless of the TracerProvider.

This change now means that the span retrieval methods can not be defined
completely by the Trace Package. Moving the requirements up to the package level.

* Addressing comments

Selecting "Tracing Context Utilities" rather than "Trace Package" to provide
clear guidance on languages that do not have static module-level functions.

Adding a section on the ability to expose these as module-level functions to ensure
that the simplified workflow of a top-level get / set span is possible.

* fixing invalid Trace Package reference

* removing unrelated change

* adding changelog entry

Co-authored-by: Carlos Alberto Cortez <calberto.cortez@gmail.com>
Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

CHANGELOG.md

@@ -77,6 +77,8 @@ Updates:
   and `RECORD_AND_SAMPLE` for consistency
   ([#938](https://github.com/open-telemetry/opentelemetry-specification/pull/938),
   [#956](https://github.com/open-telemetry/opentelemetry-specification/pull/956))
+- Move active span interaction in the Trace API to a separate class
+  ([#923](https://github.com/open-telemetry/opentelemetry-specification/pull/923))
 - Metrics SDK: Specify LastValue default aggregation for ValueObserver
   ([#984](https://github.com/open-telemetry/opentelemetry-specification/pull/984)
 - Metrics SDK: Specify TBD default aggregation for ValueRecorder

spec-compliance-matrix.md

@@ -15,6 +15,9 @@ status of the feature is not known.
 |Create TracerProvider                         | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Get a Tracer                                  | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Safe for concurrent calls                     | + | +  | + |      | +  | +    | + | +  | + | +  |
+|[Tracing Context Utilities](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracing-context-utilities)|
+|Get active Span                               |   |    |   | +    |    |      |   |    |   |    |
+|Set active Span                               |   |    |   | +    |    |      |   |    |   |    |
 |[Tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#tracer-operations)|
 |Create a new Span                             | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Get active Span                               | + | +  | + | +    | +  | +    | + | +  | + | +  |

specification/trace/api.md

@@ -11,6 +11,7 @@ Table of Contents
     * [Duration](#duration)
 * [TracerProvider](#tracerprovider)
   * [TracerProvider operations](#tracerprovider-operations)
+* [Tracing Context Utilities](#tracing-context-utilities)
 * [Tracer](#tracer)
   * [Tracer operations](#tracer-operations)
 * [SpanContext](#spancontext)
@@ -129,6 +130,22 @@ the tracer could, for example, do a look-up with its name+version in a map in
 the `TracerProvider`, or the `TracerProvider` could maintain a registry of all
 returned `Tracer`s and actively update their configuration if it changes.
 
+## Tracing Context Utilities
+
+`Tracing Context Utilities` contains all operations within tracing that
+modify the [`Context`](../context/context.md).
+
+As these utilities operate solely on the context API, they MAY be exposed
+as static methods on the trace module instead of a class.
+
+The `Tracing Context Utilities` MUST provide the following functions:
+
+- Get the currently active span
+- Set the currently active span
+
+The above methods MUST be equivalent to a single parameterized method call of
+the [`Context`](../context/context.md) management system.
+
 ## Tracer
 
 The tracer is responsible for creating `Span`s.
@@ -142,17 +159,12 @@ The `Tracer` MUST provide functions to:
 
 - [Create a new `Span`](#span-creation) (see the section on `Span`)
 
-The `Tracer` SHOULD provide methods to:
+The `Tracer` MAY provide functions to:
 
-- Get the currently active `Span`
-- Mark a given `Span` as active
+- Get the currently active span
+- Set the currently active span
 
-The `Tracer` MUST delegate to the [`Context`](../context/context.md) to perform
-these tasks, i.e. the above methods MUST do the same as a single equivalent
-method of the Context management system.
-In particular, this implies that the active span MUST not depend on the `Tracer`
-that it is queried from/was set to, as long as the tracers were obtained from
-the same `TracerProvider`.
+These functions MUST delegate to the `Tracing Context Utilities`.
 
 ## SpanContext