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 PropagationOnly Span to simplify active Span logic in Context
([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994))

Updates:

Expand Down
36 changes: 25 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)
* [Propagated Span creation](#propagated-span-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 span.

- 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` cannot be set as active in a `Context` directly, but through the use
of a [Propagated Span](#propagated-span-creation) wrapping it.
For example, a `Propagator` performing context extraction may need this.

#### Add Links

Expand Down Expand Up @@ -566,6 +562,24 @@ 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.

### Propagated Span creation

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. This is done in order to expose a `SpanContext`
as a `Span` in operations such as in-process `Span` propagation.

If a new type is required for supporting this operation, it SHOULD be named `PropagatedSpan`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please decide between "Propagated Span" and "PropagatedSpan"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Propagated Span is a concept, PropagatedSpan is the name (as Ruby does not need to expose it).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would think it's cleaner if we named the concepted PropagatedSpan too, but this is only an nipick anyway (I approved the PR)


The behavior is defined as follows:

- `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.

This functionality MUST be fully implemented in the API, and SHOULD NOT be overridable.

## Status

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