Add a Shutdown() method to *Provider SDK (#1074)

* Add a Shutdown() method to `*Provider`

* Add more precise description

* Update description of shutting down a provider

* Update CHANGELOG & spec-compliance-matrix

* Remove Shutdown function from API

Author: XSAM

CHANGELOG.md

@@ -47,6 +47,7 @@ New:
   ([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994))
 - Add Metric SDK specification (partial): covering terminology and Accumulator component
   ([#626](https://github.com/open-telemetry/opentelemetry-specification/pull/626))
+- Add `Shutdown` function to `*Provider` SDK ([#1074](https://github.com/open-telemetry/opentelemetry-specification/pull/1074))
 
 Updates:
 

spec-compliance-matrix.md

@@ -15,6 +15,7 @@ status of the feature is not known.
 |Create TracerProvider                         | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Get a Tracer                                  | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Safe for concurrent calls                     | + | +  | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/392)    | +  | +    | + | +  | + | +  |
+|Shutdown                                      |   |    |   |      |    |      |   |    |   |    |
 |[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                               |   |    |   | +    |    |      |   |    |   |    |

specification/metrics/sdk.md

@@ -154,6 +154,24 @@ implementing the [`Meter` interface](api.md#meter-interface), and
 managing the SDK instrument, the Resource, and Instrumentation Library
 metadata.
 
+#### MeterProvider
+
+##### Shutdown
+
+This method provides a way for provider to do any cleanup required.
+
+`Shutdown` MUST be called only once for each `MeterProvider` instance. After
+the call to `Shutdown`, subsequent attempts to get a `Meter` are not allowed. SDKs
+SHOULD return a valid no-op Meter for these calls, if possible.
+
+`Shutdown` SHOULD provide a way to let the caller know whether it succeeded,
+failed or timed out.
+
+`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` can be
+implemented as a blocking API or an asynchronous API which notifies the caller
+via a callback or an event. Language library authors can decide if they want to
+make the shutdown timeout configurable.
+
 #### SDK: Instrument Registration
 
 The OpenTelemetry SDK is responsible for ensuring that an individual

specification/trace/api.md

@@ -91,11 +91,13 @@ number of `TracerProvider` instances.
 
 ### TracerProvider operations
 
-The `TracerProvider` MUST provide functions to:
+The `TracerProvider` MUST provide the following functions:
 
 - Get a `Tracer`
 
-That API MUST accept the following parameters:
+#### Get a Tracer
+
+This API MUST accept the following parameters:
 
 - `name` (required): This name must identify the [instrumentation library](../overview.md#instrumentation-libraries)
   (e.g. `io.opentelemetry.contrib.mongodb`) and *not* the instrumented library.

specification/trace/sdk.md

@@ -5,7 +5,7 @@
 <summary>Table of Contents</summary>
 
 * [Sampling](#sampling)
-* [Tracer Creation](#tracer-creation)
+* [Tracer Provider](#tracer-provider)
 * [Additional Span Interfaces](#additional-span-interfaces)
 * [Span Processor](#span-processor)
 * [Span Exporter](#span-exporter)
@@ -180,7 +180,9 @@ Optional parameters:
 |present|false|true|`localParentSampled()`|
 |present|false|false|`localParentNotSampled()`|
 
-## Tracer Creation
+## Tracer Provider
+
+### Tracer Creation
 
 New `Tracer` instances are always created through a `TracerProvider` (see
 [API](api.md#tracerprovider)). The `name` and `version` arguments
@@ -201,6 +203,24 @@ Note: Implementation-wise, this could mean that `Tracer` instances have a
 reference to their `TracerProvider` and access configuration only via this
 reference.
 
+### Shutdown
+
+This method provides a way for provider to do any cleanup required.
+
+`Shutdown` MUST be called only once for each `TracerProvider` instance. After
+the call to `Shutdown`, subsequent attempts to get a `Tracer` are not allowed. SDKs
+SHOULD return a valid no-op Tracer for these calls, if possible.
+
+`Shutdown` SHOULD provide a way to let the caller know whether it succeeded,
+failed or timed out.
+
+`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` can be
+implemented as a blocking API or an asynchronous API which notifies the caller
+via a callback or an event. Language library authors can decide if they want to
+make the shutdown timeout configurable.
+
+`Shutdown` MUST be implemented at least by invoking `Shutdown` within all internal processors.
+
 ## Additional Span Interfaces
 
 The [API-level definition for Span's interface](api.md#span-operations)