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

Define Propagation-only Span to simplify active Span logic in Context. #994

Merged
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ New:
[#946](https://github.com/open-telemetry/opentelemetry-specification/pull/946))
- Update the header name for otel baggage, and version date
([#981](https://github.com/open-telemetry/opentelemetry-specification/pull/981))
- Define DefaultSpan to simplify active Span logic in Context
([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994))

Updates:

Expand Down
30 changes: 19 additions & 11 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Table of Contents
* [End](#end)
* [Record Exception](#record-exception)
* [Span lifetime](#span-lifetime)
* [DefaultSpan creation](#defaultspan-creation)
* [Status](#status)
* [StatusCanonicalCode](#statuscanonicalcode)
* [Status creation](#status-creation)
Expand Down Expand Up @@ -352,18 +353,13 @@ parent is remote.

#### Determining the Parent Span from a Context

When a new `Span` is created from a `Context`, the `Context` may contain:
When a new `Span` is created from a `Context`, the `Context` may contain a `Span`
representing the currently active instance, and will be used as parent.
If there is no `Span` in the `Context`, the newly created `Span` will be a root instance.
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

- A current `Span`
- An extracted `SpanContext`
- A current `Span` and an extracted `SpanContext`
- Neither a current `Span` nor an extracted `Span` context

The parent should be selected in the following order of precedence:

- Use the current `Span`, if available.
- Use the extracted `SpanContext`, if available.
- There is no parent. Create a root `Span`.
A `SpanContext` may set as the active instance in a `Context` (for example, by a `Propagator`
performing context extraction) through the use of a [DefaultSpan](#defaultspan-creation)
wrapping it.
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

#### Add Links

Expand Down Expand Up @@ -566,6 +562,18 @@ timestamps to the Span object:
Start and end time as well as Event's timestamps MUST be recorded at a time of a
calling of corresponding API.

### DefaultSpan creation
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

The API MUST provide an operation for wrapping a `SpanContext` with an object
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
implementing the `Span` interface, known as `DefaultSpan`. This is done in order to expose
a `SpanContext` as a `Span` in operations such as in-process `Span` propagation.

- `GetContext()` MUST return the wrapped `SpanContext`.
- `IsRecording` MUST return `false` to signal that events, attributes and other elements
are not being recorded, i.e. they are being dropped.
Oberon00 marked this conversation as resolved.
Show resolved Hide resolved

The remaining functionality of `Span` must be defined as no-op operations.

## Status

`Status` interface represents the status of a finished `Span`. It's composed of
Expand Down