From 03fa286f60dbe3f0aa584bb451f5c1a1a76ab7ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 25 Aug 2020 19:59:37 +0200 Subject: [PATCH 01/12] Spans must have parent Contexts instead of parent Span(Context)s. --- specification/trace/api.md | 42 ++++++++++++++++---------------------- specification/trace/sdk.md | 7 +++++-- 2 files changed, 23 insertions(+), 26 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index ddda9ac8c5b..7a7b6981988 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -219,8 +219,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - The span name - An immutable [`SpanContext`](#spancontext) that uniquely identifies the `Span` -- A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext), - or null +- A parent span in the form of a (possibly empty) [`Context`](../) - A [`SpanKind`](#spankind) - A start timestamp - An end timestamp @@ -286,24 +285,19 @@ directly. All `Span`s MUST be created via a `Tracer`. There MUST NOT be any API for creating a `Span` other than with a [`Tracer`](#tracer). -When creating a new `Span`, the `Tracer` MUST allow the caller to specify the -new `Span`'s parent in the form of a `Span` or `SpanContext`. The `Tracer` -SHOULD create each new `Span` as a child of its active `Span`, unless an -explicit parent is provided or the option to create a span without a parent is -selected. - `Span` creation MUST NOT set the newly created `Span` as the currently active `Span` by default, but this functionality MAY be offered additionally -as a separate operation. +as a separate operation. If that functionality is provided, it MUST ONLY accept a +full [`Context`](../context/context.md) (or implicitly use the current `Context`) +but it MUST NOT accept only a `Span` or `SpanContext` +(that would be prone to lose information on the parent span's `Context`). The API MUST accept the following parameters: - The span name. This is a required parameter. -- The parent `Span` or a `Context` containing a parent `Span` or `SpanContext`, - and whether the new `Span` should be a root `Span`. API MAY also have an - option for implicit parenting from the current context as a default behavior. - See [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) - for guidance on `Span` parenting from explicit and implicit `Context`s. +- The parent `Context` or an indication that the new `Span` should be a root `Span`. + The API MAY also have an option for implicitly using + the current context as parent as a default behavior. - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified. - [`Attributes`](../common/common.md#attributes). Additionally, these attributes may be used to make a sampling decision as noted in [sampling @@ -333,20 +327,20 @@ created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the parent is remote. -#### Determining the Parent Span from a Context +#### Effective Span -When a new `Span` is created from a `Context`, the `Context` may contain: +The *effective span* of a [`Context`](../context/context.md) is the first of the +following that is available in it (with the respective key if applicable): -- A current `Span` -- An extracted `SpanContext` -- A current `Span` and an extracted `SpanContext` -- Neither a current `Span` nor an extracted `Span` context +1. An actual `Span` object. +2. An extracted `SpanContext` + (that MAY be wrapped in an otherwise empty non-recording `Span`). +3. Nothing (which SHOULD be represented as a non-null empty `SpanContext` or `Span`). -The parent should be selected in the following order of precedence: +The API MUST provide functionality to get the effective Span from a `Context`. -- Use the current `Span`, if available. -- Use the extracted `SpanContext`, if available. -- There is no parent. Create a root `Span`. +Given a `Span` with its parent `Context`, the semantic parent Span is the +effective span in that parent `Context`. #### Add Links diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index b1afff388f0..57c131c4560 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -194,8 +194,11 @@ Thus, the SDK specification defines sets of possible requirements for access all information that was added to the span, as listed [in the API spec](api.md#span-data-members). In particular, it MUST also be able to access - the `InstrumentationLibrary` and `Resource` information (implicitly) - associated with the span. + the full parent [`Context`](../context/cotnext.md), + `InstrumentationLibrary` and `Resource` information + (implicitly) associated with the span. + Note: The `Context` of the span itself cannot be made available, + because a Span may be (active) in several or no `Context`'s at any time. It must also be able to reliably determine whether the Span has ended (some languages might implement this by having an end timestamp of `null`, others might have an explicit `hasEnded` boolean). From d572726eeaafb09c8cbc538e4fe186222a47263e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 25 Aug 2020 20:16:49 +0200 Subject: [PATCH 02/12] Add CHANGELOG. --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3613d1e219a..08c4a44d5ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,12 @@ New: the absence of an installed SDK - Add Span API and semantic conventions for recording exceptions ([#697](https://github.com/open-telemetry/opentelemetry-specification/pull/697)) +- Spans have parent `Context`s instead of just `SpanContext`s + ([#875](https://github.com/open-telemetry/opentelemetry-specification/pull/875)) + * A full Context is the only way to specify a parent of a span + SpanContext or even Span are not allowed anymore. + * Readable spans MUST provide a way to retrieve the full parent context. + Updates: From 2b5182ba16ea3624b76aa3a95b706046ec57b804 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 25 Aug 2020 20:17:00 +0200 Subject: [PATCH 03/12] Fix links, TOC, add note for ReadableSpan. --- specification/trace/api.md | 34 +++++++++++++++++----------------- specification/trace/sdk.md | 6 +++++- 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 7a7b6981988..f1085849385 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -19,8 +19,8 @@ Table of Contents * [IsRemote](#isremote) * [Span](#span) * [Span creation](#span-creation) - * [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) * [Add Links](#add-links) + * [Effective Span](#effective-span) * [Span operations](#span-operations) * [Get Context](#get-context) * [IsRecording](#isrecording) @@ -219,7 +219,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - The span name - An immutable [`SpanContext`](#spancontext) that uniquely identifies the `Span` -- A parent span in the form of a (possibly empty) [`Context`](../) +- A parent span in the form of a (possibly empty) [`Context`](../context/context.md) - A [`SpanKind`](#spankind) - A start timestamp - An end timestamp @@ -327,21 +327,6 @@ created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the parent is remote. -#### Effective Span - -The *effective span* of a [`Context`](../context/context.md) is the first of the -following that is available in it (with the respective key if applicable): - -1. An actual `Span` object. -2. An extracted `SpanContext` - (that MAY be wrapped in an otherwise empty non-recording `Span`). -3. Nothing (which SHOULD be represented as a non-null empty `SpanContext` or `Span`). - -The API MUST provide functionality to get the effective Span from a `Context`. - -Given a `Span` with its parent `Context`, the semantic parent Span is the -effective span in that parent `Context`. - #### Add Links During the `Span` creation user MUST have the ability to record links to other `Span`s. @@ -362,6 +347,21 @@ The Span creation API MUST provide: Links SHOULD preserve the order in which they're set. +### Effective Span + +The *effective span* of a [`Context`](../context/context.md) is the first of the +following that is available in it (with the respective key if applicable): + +1. An actual `Span` object. +2. An extracted `SpanContext` + (that MAY be wrapped in an otherwise empty non-recording `Span`). +3. Nothing (which SHOULD be represented as a non-null empty `SpanContext` or `Span`). + +The API MUST provide functionality to get the effective Span from a `Context`. + +Given a `Span` with its parent `Context`, the semantic parent Span is the +effective span in that parent `Context`. + ### Span operations With the exception of the function to retrieve the `Span`'s `SpanContext` and diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 57c131c4560..fb4a613a8af 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -194,15 +194,19 @@ Thus, the SDK specification defines sets of possible requirements for access all information that was added to the span, as listed [in the API spec](api.md#span-data-members). In particular, it MUST also be able to access - the full parent [`Context`](../context/cotnext.md), + the full parent [`Context`](../context/context.md), `InstrumentationLibrary` and `Resource` information (implicitly) associated with the span. + Note: The `Context` of the span itself cannot be made available, because a Span may be (active) in several or no `Context`'s at any time. It must also be able to reliably determine whether the Span has ended (some languages might implement this by having an end timestamp of `null`, others might have an explicit `hasEnded` boolean). + Note: The semantic parent span within the parent `Context` + is the [effective span](api.md#effective-span) within it. + A function receiving this as argument might not be able to modify the Span. Note: Typically this will be implemented with a new interface or From 14c9ad731a3bb8e37d07cff025a9e0ba2ae4501d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 25 Aug 2020 20:19:30 +0200 Subject: [PATCH 04/12] Lint. --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 08c4a44d5ac..a1336fb2374 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,7 +21,6 @@ New: SpanContext or even Span are not allowed anymore. * Readable spans MUST provide a way to retrieve the full parent context. - Updates: - Add semantic convention for NGINX custom HTTP 499 status code. From a7e70658e3e3abd084413bbad00d9ec243c0953b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Sep 2020 17:56:35 +0200 Subject: [PATCH 05/12] Remove storage of Context. --- CHANGELOG.md | 8 +++----- specification/trace/sdk.md | 11 ++--------- 2 files changed, 5 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0dd3e33e9fd..f5441b5afc7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,12 +56,10 @@ Updates: ([#911](https://github.com/open-telemetry/opentelemetry-specification/pull/911)) - Explicitly specify the SpanContext APIs IsValid and IsRemote as required ([#914](https://github.com/open-telemetry/opentelemetry-specification/pull/914)) -- Spans have parent `Context`s instead of just `SpanContext`s +- A full `Context` is the only way to specify a parent of a `Span` + `SpanContext` or even `Span` are not allowed anymore. ([#875](https://github.com/open-telemetry/opentelemetry-specification/pull/875)) - * A full Context is the only way to specify a parent of a span - SpanContext or even Span are not allowed anymore. - * Readable spans MUST provide a way to retrieve the full parent context. - + ## v0.6.0 (07-01-2020) New: diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index e1172492222..60bed14b502 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -210,19 +210,12 @@ Thus, the SDK specification defines sets of possible requirements for access all information that was added to the span, as listed [in the API spec](api.md#span-data-members). In particular, it MUST also be able to access - the full parent [`Context`](../context/context.md), - `InstrumentationLibrary` and `Resource` information - (implicitly) associated with the span. - - Note: The `Context` of the span itself cannot be made available, - because a Span may be (active) in several or no `Context`'s at any time. + the `InstrumentationLibrary` and `Resource` information (implicitly) + associated with the span. It must also be able to reliably determine whether the Span has ended (some languages might implement this by having an end timestamp of `null`, others might have an explicit `hasEnded` boolean). - Note: The semantic parent span within the parent `Context` - is the [effective span](api.md#effective-span) within it. - A function receiving this as argument might not be able to modify the Span. Note: Typically this will be implemented with a new interface or From e6e5d9726620cff32f660d1e2c2258adcef839de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Sep 2020 18:07:29 +0200 Subject: [PATCH 06/12] Add Context to OnStart. --- specification/trace/sdk.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 60bed14b502..f72fb9b3c2f 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -276,7 +276,7 @@ in the SDK: ### Interface definition -#### OnStart(Span) +#### OnStart `OnStart` is called when a span is started. This method is called synchronously on the thread that started the span, therefore it should not block or throw @@ -284,11 +284,14 @@ exceptions. **Parameters:** -* `Span` - a [read/write span object](#additional-span-interfaces) for the started span. +* `span` - a [read/write span object](#additional-span-interfaces) for the started span. It SHOULD be possible to keep a reference to this span object and updates to the span SHOULD be reflected in it. For example, this is useful for creating a SpanProcessor that periodically evaluates/prints information about all active span from a background thread. +* `parentContext` - the parent `Context` of the span that the SDK determined + (the explicitly passed `Context`, the current `Context` or an empty `Context` + if that was explicitly requested). **Returns:** `Void` From 18a66aaca32d3623043fc89b6b51641feb8205b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Sep 2020 18:09:54 +0200 Subject: [PATCH 07/12] Remove misplaced paragraph. --- specification/trace/api.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 7e0c38b371f..c2f037c2806 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -308,17 +308,15 @@ There MUST NOT be any API for creating a `Span` other than with a [`Tracer`](#tr `Span` creation MUST NOT set the newly created `Span` as the currently active `Span` by default, but this functionality MAY be offered additionally -as a separate operation. If that functionality is provided, it MUST ONLY accept a -full [`Context`](../context/context.md) (or implicitly use the current `Context`) -but it MUST NOT accept only a `Span` or `SpanContext` -(that would be prone to lose information on the parent span's `Context`). +as a separate operation. The API MUST accept the following parameters: - The span name. This is a required parameter. - The parent `Context` or an indication that the new `Span` should be a root `Span`. The API MAY also have an option for implicitly using - the current context as parent as a default behavior. + the current Context as parent as a default behavior. + This API MUST NOT accept only a `Span` or `SpanContext`. - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified. - [`Attributes`](../common/common.md#attributes). Additionally, these attributes may be used to make a sampling decision as noted in [sampling From 224531d45045f59c2c9e3650d561aa10747b4308 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Sep 2020 18:13:10 +0200 Subject: [PATCH 08/12] Wording. --- specification/trace/api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index c2f037c2806..671ab278e85 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -316,7 +316,10 @@ The API MUST accept the following parameters: - The parent `Context` or an indication that the new `Span` should be a root `Span`. The API MAY also have an option for implicitly using the current Context as parent as a default behavior. - This API MUST NOT accept only a `Span` or `SpanContext`. + This API MUST NOT accept a `Span` or `SpanContext` as parent, only a full `Context`. + + The semantic parent of the Span MUST be determined according to the rules + described in the [Effective Span section](#effective-span). - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified. - [`Attributes`](../common/common.md#attributes). Additionally, these attributes may be used to make a sampling decision as noted in [sampling From aa67440053c9b33e69fc9da0f60dcaca0900faf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Sep 2020 18:22:21 +0200 Subject: [PATCH 09/12] Whitespace for lint. --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5441b5afc7..16d4b09b27c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,10 +56,10 @@ Updates: ([#911](https://github.com/open-telemetry/opentelemetry-specification/pull/911)) - Explicitly specify the SpanContext APIs IsValid and IsRemote as required ([#914](https://github.com/open-telemetry/opentelemetry-specification/pull/914)) -- A full `Context` is the only way to specify a parent of a `Span` +- A full `Context` is the only way to specify a parent of a `Span` `SpanContext` or even `Span` are not allowed anymore. ([#875](https://github.com/open-telemetry/opentelemetry-specification/pull/875)) - + ## v0.6.0 (07-01-2020) New: From cf57fdd13682f4cfd79d0b6f1312406d1f0ffcc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Sep 2020 20:10:33 +0200 Subject: [PATCH 10/12] Typo. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 16d4b09b27c..1ccdbc7d44e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,7 +56,7 @@ Updates: ([#911](https://github.com/open-telemetry/opentelemetry-specification/pull/911)) - Explicitly specify the SpanContext APIs IsValid and IsRemote as required ([#914](https://github.com/open-telemetry/opentelemetry-specification/pull/914)) -- A full `Context` is the only way to specify a parent of a `Span` +- A full `Context` is the only way to specify a parent of a `Span`. `SpanContext` or even `Span` are not allowed anymore. ([#875](https://github.com/open-telemetry/opentelemetry-specification/pull/875)) From f98a5168efb1e95f9cd4668789f58543e27f0640 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Sat, 19 Sep 2020 12:41:38 +0200 Subject: [PATCH 11/12] Revert no longer needed "effective span" wording. --- specification/trace/api.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 88cb95b4b2b..2a5e19e0fe7 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -19,8 +19,8 @@ Table of Contents * [IsRemote](#isremote) * [Span](#span) * [Span creation](#span-creation) + * [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) * [Add Links](#add-links) - * [Effective Span](#effective-span) * [Span operations](#span-operations) * [Get Context](#get-context) * [IsRecording](#isrecording) @@ -319,7 +319,7 @@ The API MUST accept the following parameters: This API MUST NOT accept a `Span` or `SpanContext` as parent, only a full `Context`. The semantic parent of the Span MUST be determined according to the rules - described in the [Effective Span section](#effective-span). + described in [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context). - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified. - [`Attributes`](../common/common.md#attributes). Additionally, these attributes may be used to make a sampling decision as noted in [sampling @@ -349,6 +349,21 @@ created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the parent is remote. +#### Determining the Parent Span from a Context + +When a new `Span` is created from a `Context`, the `Context` may contain: + +- 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`. + #### Add Links During the `Span` creation user MUST have the ability to record links to other `Span`s. @@ -371,21 +386,6 @@ The Span creation API MUST provide: Links SHOULD preserve the order in which they're set. -### Effective Span - -The *effective span* of a [`Context`](../context/context.md) is the first of the -following that is available in it (with the respective key if applicable): - -1. An actual `Span` object. -2. An extracted `SpanContext` - (that MAY be wrapped in an otherwise empty non-recording `Span`). -3. Nothing (which SHOULD be represented as a non-null empty `SpanContext` or `Span`). - -The API MUST provide functionality to get the effective Span from a `Context`. - -Given a `Span` with its parent `Context`, the semantic parent Span is the -effective span in that parent `Context`. - ### Span operations With the exception of the function to retrieve the `Span`'s `SpanContext` and From ad4a72f35c21b4218e23b55e037b3655bfd67499 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Sat, 19 Sep 2020 12:44:17 +0200 Subject: [PATCH 12/12] Revert changes to "a span encapsulates..." --- specification/trace/api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 2a5e19e0fe7..6d5b94ac5bd 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -240,7 +240,8 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - The span name - An immutable [`SpanContext`](#spancontext) that uniquely identifies the `Span` -- A parent span in the form of a (possibly empty) [`Context`](../context/context.md) +- A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext), + or null - A [`SpanKind`](#spankind) - A start timestamp - An end timestamp