From 6d492577a68d6de0cca991051d800234f6f4eee8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 27 Feb 2023 17:22:35 +0100 Subject: [PATCH 1/6] Clarify SDK ReadableSpan's parent Context. --- CHANGELOG.md | 4 ++++ specification/trace/api.md | 3 +++ specification/trace/sdk.md | 10 ++++++++-- 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 488693e42f9..27f76c42228 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ release. ### Traces +* Clarify required parent information in ReadableSpan. Technically a relaxation, + but previously it was easy to overlook certain properties were required. + (#TODO)[https://github.com/open-telemetry/opentelemetry-specification/pull/TODO] + ### Metrics - Add metric requirement levels "Required", "Recommended", and "Opt-In". diff --git a/specification/trace/api.md b/specification/trace/api.md index d27cbacc9f7..cebd1f91ff3 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -224,6 +224,9 @@ specification](https://www.w3.org/TR/trace-context/#tracestate-header). For specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. +`IsRemote´, a boolean indicating whether the SpanContext was received from somewhere +else or locally generated, see [IsRemote](#isremote). + The API MUST implement methods to create a `SpanContext`. These methods SHOULD be the only way to create a `SpanContext`. This functionality MUST be fully implemented in the API, and SHOULD NOT be overridable. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 2e5b0dd46dc..fb7bf7773bd 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -120,8 +120,14 @@ Thus, the SDK specification defines sets of possible requirements for * **Readable span**: A function receiving this as argument MUST be able to access all information that was added to the span, as listed - [in the API spec](api.md#span). In particular, it MUST also be - able to access the `InstrumentationScope` [since 1.10.0] and `Resource` + in the API spec for [Span](api.md#span) (Note: this also includes all + e.g. all its [Span Context](api.md#spancontext) properties). + + SDKs MAY choose not to expose (and store) the full parent [Context](../context/README.md) + of the Span but MUST expose at least the full parent [SpanContext](api.md#spancontext). + + In particular, it MUST also be able to access the `InstrumentationScope` + [since 1.10.0] and `Resource` information (implicitly) associated with the span. For backwards compatibility it MUST also be able to access the `InstrumentationLibrary` [deprecated since 1.10.0] having the same name and version values as the From 8258d8021c0a8850c2f484ad69f78c843c8b84b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 27 Feb 2023 17:28:36 +0100 Subject: [PATCH 2/6] Fill in PR#. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27f76c42228..8b7ca58264f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ release. * Clarify required parent information in ReadableSpan. Technically a relaxation, but previously it was easy to overlook certain properties were required. - (#TODO)[https://github.com/open-telemetry/opentelemetry-specification/pull/TODO] + [#3257](https://github.com/open-telemetry/opentelemetry-specification/pull/3257) ### Metrics From b73f5387e06d353cb70a20dcf8d3b2306645cd22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 27 Feb 2023 17:29:51 +0100 Subject: [PATCH 3/6] Remove fragment --- specification/trace/sdk.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index fb7bf7773bd..ded7b28f524 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -120,8 +120,7 @@ Thus, the SDK specification defines sets of possible requirements for * **Readable span**: A function receiving this as argument MUST be able to access all information that was added to the span, as listed - in the API spec for [Span](api.md#span) (Note: this also includes all - e.g. all its [Span Context](api.md#spancontext) properties). + in the API spec for [Span](api.md#span). SDKs MAY choose not to expose (and store) the full parent [Context](../context/README.md) of the Span but MUST expose at least the full parent [SpanContext](api.md#spancontext). From 4f83da5866744c9b4ec74f0506420d7c9ccd274b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 27 Feb 2023 17:37:43 +0100 Subject: [PATCH 4/6] More rewording --- specification/trace/sdk.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index ded7b28f524..ec69c39b8fd 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -120,19 +120,19 @@ Thus, the SDK specification defines sets of possible requirements for * **Readable span**: A function receiving this as argument MUST be able to access all information that was added to the span, as listed - in the API spec for [Span](api.md#span). + in the API spec for [Span](api.md#span). Note: Below, a few particular properties + are called out for clarity, but for the complete list of required properties, + the [Span API spec](api.md#span) is authoritative. - SDKs MAY choose not to expose (and store) the full parent [Context](../context/README.md) - of the Span but MUST expose at least the full parent [SpanContext](api.md#spancontext). - - In particular, it MUST also be able to access the `InstrumentationScope` - [since 1.10.0] and `Resource` - information (implicitly) associated with the span. For backwards compatibility + A function receiving this as argument MUST be able to access + the `InstrumentationScope` [since 1.10.0] and `Resource` information + (implicitly) associated with the span. For backwards compatibility it MUST also be able to access the `InstrumentationLibrary` [deprecated since 1.10.0] having the same name and version values as the `InstrumentationScope`. - It must also be able to reliably determine whether the Span has ended + A function receiving this as argument MUST must 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). @@ -140,6 +140,10 @@ Thus, the SDK specification defines sets of possible requirements for available for exporters to report as described in the [exporters](../common/mapping-to-non-otlp.md#dropped-attributes-count) specification. + As an exception to the authoritative set of span properties defined in the API spec, + implementations MAY choose not to expose (and store) the full parent [Context](../context/README.md) + of the Span but they MUST expose at least the full parent [SpanContext](api.md#spancontext). + 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 15818aea340951dc284c8ef6f8ee84d87239b517 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 27 Feb 2023 17:47:22 +0100 Subject: [PATCH 5/6] Syntax. --- specification/trace/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index cebd1f91ff3..5d665013c3a 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -197,7 +197,7 @@ The `Tracer` MUST provide functions to: - [Create a new `Span`](#span-creation) (see the section on `Span`) -## SpanContext +´## SpanContext A `SpanContext` represents the portion of a `Span` which must be serialized and propagated along side of a distributed context. `SpanContext`s are immutable. @@ -224,7 +224,7 @@ specification](https://www.w3.org/TR/trace-context/#tracestate-header). For specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. -`IsRemote´, a boolean indicating whether the SpanContext was received from somewhere +`IsRemote`, a boolean indicating whether the SpanContext was received from somewhere else or locally generated, see [IsRemote](#isremote). The API MUST implement methods to create a `SpanContext`. These methods SHOULD be the only way to From 1e71cadaf2fb0d7460c4fada55504df23f30e8ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 28 Feb 2023 14:26:02 +0100 Subject: [PATCH 6/6] Fix stray char --- 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 5d665013c3a..59a4b390a97 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -197,7 +197,7 @@ The `Tracer` MUST provide functions to: - [Create a new `Span`](#span-creation) (see the section on `Span`) -´## SpanContext +## SpanContext A `SpanContext` represents the portion of a `Span` which must be serialized and propagated along side of a distributed context. `SpanContext`s are immutable.