Skip to content

Commit

Permalink
Moving active span interaction To TracerProvider
Browse files Browse the repository at this point in the history
Fixes open-telemetry#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.
  • Loading branch information
toumorokoshi committed Sep 6, 2020
1 parent d4dfd46 commit 5f70f81
Showing 1 changed file with 29 additions and 10 deletions.
39 changes: 29 additions & 10 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Table of Contents
* [Time](#time)
* [Timestamp](#timestamp)
* [Duration](#duration)
* [Tracer Package](#trace-package)
* [TracerProvider](#tracerprovider)
* [TracerProvider operations](#tracerprovider-operations)
* [Tracer](#tracer)
Expand Down Expand Up @@ -74,6 +75,18 @@ A duration is the elapsed time between two events.
* The minimal precision is milliseconds.
* The maximal precision is nanoseconds.

## Trace package

The `Trace Package` is the package containing the TracerProvider and Tracer
API classes. In some languages, this may also be referred to as a module.

The `Trace Package` MAY provide the following functions:

- Get the currently active span
- Set the currently active span

Both of these operations MUST delegate to the configured `TracerProvider`.

## TracerProvider

`Tracer`s can be accessed with a `TracerProvider`.
Expand All @@ -97,7 +110,7 @@ number of `TracerProvider` instances.

The `TracerProvider` MUST provide functions to:

- Get a `Tracer`
#### Get a `Tracer`

That API MUST accept the following parameters:

Expand Down Expand Up @@ -129,6 +142,17 @@ 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.

#### Get and set the currently active span

The `TracerProvider` 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. However, `TracerProvider` implementations
are not required to behave the same way.

For example, different `TracerProvider` implementations may use different context
keys to get and set the currently active span. This would result in a different active
span depending on the `TracerProvider` you are calling to.

## Tracer

The tracer is responsible for creating `Span`s.
Expand All @@ -142,17 +166,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 `TracerProvider`.

## SpanContext

Expand Down

0 comments on commit 5f70f81

Please sign in to comment.