Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify context interaction for trace module #1063

Merged
merged 11 commits into from
Oct 15, 2020
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@ 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))
- Clarify context interaction for trace module
([#1063](https://github.com/open-telemetry/opentelemetry-specification/pull/1063))

Updates:

Expand Down
35 changes: 19 additions & 16 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Table of Contents
* [Duration](#duration)
* [TracerProvider](#tracerprovider)
* [TracerProvider operations](#tracerprovider-operations)
* [Tracing Context Utilities](#tracing-context-utilities)
* [Context Interaction](#context-interaction)
* [Tracer](#tracer)
* [Tracer operations](#tracer-operations)
* [SpanContext](#spancontext)
Expand Down Expand Up @@ -130,21 +130,31 @@ 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
## Context Interaction

`Tracing Context Utilities` contains all operations within tracing that
modify the [`Context`](../context/context.md).
This section defines all operations within trace module that interact with the
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
[`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 API MUST provide the following functionality to interact with a `Context`
instance:

The `Tracing Context Utilities` MUST provide the following functions:
- Extract the `Span` from a `Context` instance
- Insert the `Span` to a `Context` instance

The functionality listed above is necessary because API users SHOULD NOT have
access to the [Context's Key](../context/context.md#create-a-key).
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

If the language has support for implicitly propagated `Context`, see
[here](../context/context.md#optional-global-operations). The API SHOULD provide
the following functionality:
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

- Get the currently active span
- Set the currently active span
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

The above methods MUST be equivalent to a single parameterized method call of
the [`Context`](../context/context.md) management system.
All the above functionalities operate solely on the context API, and they MAY be
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
exposed as static methods on the trace module, as static methods on a class
inside the trace module (it MAY be named `TracingContextUtilities`), or on the
[`Tracer`](#tracer) class.
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

## Tracer

Expand All @@ -159,13 +169,6 @@ The `Tracer` MUST provide functions to:

- [Create a new `Span`](#span-creation) (see the section on `Span`)

The `Tracer` MAY provide functions to:
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

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

These functions MUST delegate to the `Tracing Context Utilities`.

## SpanContext

A `SpanContext` represents the portion of a `Span` which must be serialized and
Expand Down