From 5aa9eba999679eb1fd73fe7f42e86a3ea59cd8db Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 23 Sep 2020 20:21:56 +0200 Subject: [PATCH 1/9] Define DefaultSpan to simplify active Span in Context. --- specification/trace/api.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index f149215c25b..4cfaa18034c 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) + * [DefaultSpan creation](#defaultspan-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 instance. -- 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. #### Add Links @@ -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 + +The API MUST provide an operation for wrapping a `SpanContext` with an object +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. + +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 From 50e8628f9ce134b0f227be5d5c424b0b0979f263 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 23 Sep 2020 20:27:23 +0200 Subject: [PATCH 2/9] Update CHANGELOG. --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6733bd6243..5158bcc5337 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 DefaultSpan to simplify active Span logic in Context + ([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994)) Updates: From 7cb095f41b46612b1ba18f760b77d2a5128753c9 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 23 Sep 2020 22:06:36 +0200 Subject: [PATCH 3/9] Update specification/trace/api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 4cfaa18034c..8d9a3426488 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -355,7 +355,7 @@ parent is remote. 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. +If there is no `Span` in the `Context`, the newly created `Span` will be 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) From b956967e0a2d82b4747b43e706202bd62d412ce8 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 23 Sep 2020 22:07:04 +0200 Subject: [PATCH 4/9] Update specification/trace/api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/trace/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 8d9a3426488..22bb6bc701f 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -357,9 +357,9 @@ 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 `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. +A `SpanContext` cannot be set as active in a `Context` directly, +but through the use of a [DefaultSpan](#defaultspan-creation) wrapping it. +For example, a `Propagator` performing context extraction, may need this. #### Add Links From 46975c9900973b83c2423c97127e17355d136d7f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 24 Sep 2020 00:58:48 +0200 Subject: [PATCH 5/9] Apply feedback. --- specification/trace/api.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 22bb6bc701f..ff890e55475 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -31,7 +31,7 @@ Table of Contents * [End](#end) * [Record Exception](#record-exception) * [Span lifetime](#span-lifetime) - * [DefaultSpan creation](#defaultspan-creation) + * [PropagationOnly Span creation](#propagationonly-span-creation) * [Status](#status) * [StatusCanonicalCode](#statuscanonicalcode) * [Status creation](#status-creation) @@ -357,9 +357,9 @@ 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 `SpanContext` cannot be set as active in a `Context` directly, -but through the use of a [DefaultSpan](#defaultspan-creation) wrapping it. -For example, a `Propagator` performing context extraction, may need this. +A `SpanContext` cannot be set as active in a `Context` directly, but through the use +of a [PropagationOnly Span](#propagationonly-span-creation) wrapping it. +For example, a `Propagator` performing context extraction may need this. #### Add Links @@ -562,17 +562,21 @@ 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 +### PropagationOnly Span creation The API MUST provide an operation for wrapping a `SpanContext` with an object -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. +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 `PropagatorOnlySpan`. + +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. +The remaining functionality of `Span` MUST be defined as no-op operations. ## Status From 8325974e15e046e8a4868e543aea50da543b1e05 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 24 Sep 2020 01:00:38 +0200 Subject: [PATCH 6/9] Specify the SDK must not override it. --- specification/trace/api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/trace/api.md b/specification/trace/api.md index ff890e55475..0633458c312 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -578,6 +578,9 @@ The behavior is defined as follows: The remaining functionality of `Span` MUST be defined as no-op operations. +Note: This is expected to be fully implemented in the API, and MUST NOT be overridable +by the SDK. + ## Status `Status` interface represents the status of a finished `Span`. It's composed of From e42edc039889d5279a8195e13b81eddf6121b5a4 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 24 Sep 2020 01:02:18 +0200 Subject: [PATCH 7/9] Update CHANGELOG. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5158bcc5337..7432dc7b6da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,7 +31,7 @@ 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 +- Define PropagationOnly Span to simplify active Span logic in Context ([#994](https://github.com/open-telemetry/opentelemetry-specification/pull/994)) Updates: From 4ace969a3246b4aed03c1ccfce6f41c954a8a35f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 24 Sep 2020 15:55:55 +0200 Subject: [PATCH 8/9] Rename to PropagatedSpan. --- specification/trace/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 0633458c312..99433636e24 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -31,7 +31,7 @@ Table of Contents * [End](#end) * [Record Exception](#record-exception) * [Span lifetime](#span-lifetime) - * [PropagationOnly Span creation](#propagationonly-span-creation) + * [Propagated Span creation](#propagated-span-creation) * [Status](#status) * [StatusCanonicalCode](#statuscanonicalcode) * [Status creation](#status-creation) @@ -358,7 +358,7 @@ 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 `SpanContext` cannot be set as active in a `Context` directly, but through the use -of a [PropagationOnly Span](#propagationonly-span-creation) wrapping it. +of a [Propagated Span](#propagated-span-creation) wrapping it. For example, a `Propagator` performing context extraction may need this. #### Add Links @@ -562,13 +562,13 @@ 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. -### PropagationOnly Span creation +### 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 `PropagatorOnlySpan`. +If a new type is required for supporting this operation, it SHOULD be named `PropagatedSpan`. The behavior is defined as follows: From 311a28d86f9119313214997d6ff27b3e708390ec Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 24 Sep 2020 16:02:37 +0200 Subject: [PATCH 9/9] More feedback. --- specification/trace/api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 99433636e24..c819b1bfdb0 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -578,8 +578,7 @@ The behavior is defined as follows: The remaining functionality of `Span` MUST be defined as no-op operations. -Note: This is expected to be fully implemented in the API, and MUST NOT be overridable -by the SDK. +This functionality MUST be fully implemented in the API, and SHOULD NOT be overridable. ## Status