diff --git a/CHANGELOG.md b/CHANGELOG.md index b6733bd6243..7432dc7b6da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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: diff --git a/specification/trace/api.md b/specification/trace/api.md index f149215c25b..c819b1bfdb0 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -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) @@ -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 @@ -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 +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`. + +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. + +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