From d14c9b7a74328c22e5d2223c4ddcaca5630aceae Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 25 Sep 2020 01:32:06 +0200 Subject: [PATCH] Define Propagation-only Span to simplify active Span logic in Context. (#994) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Define DefaultSpan to simplify active Span in Context. * Update CHANGELOG. * Update specification/trace/api.md Co-authored-by: Christian Neumüller * Update specification/trace/api.md Co-authored-by: Christian Neumüller * Apply feedback. * Specify the SDK must not override it. * Update CHANGELOG. * Rename to PropagatedSpan. * More feedback. Co-authored-by: Christian Neumüller --- CHANGELOG.md | 2 ++ specification/trace/api.md | 36 +++++++++++++++++++++++++----------- 2 files changed, 27 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7aab723ca50..1dc13754b94 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 b7816e3920c..4312dbc761d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -32,6 +32,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) @@ -363,18 +364,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 @@ -577,6 +573,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