From b89b9dbdbaa596de1756b11a711dd842a8fc0261 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 10:19:20 +0200 Subject: [PATCH 01/14] Trace SDK: Provide definitions for readable and read/write span. --- CHANGELOG.md | 2 ++ specification/trace/sdk.md | 44 ++++++++++++++++++++++++++------------ 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e64dd46573..33ad995f2aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ the release. - Clarify Tracer vs TracerProvider in tracing API and SDK spec. Most importantly: * Configuration should be stored not per Tracer but in the TracerProvider. * Active spans are not per Tracer. +- Provide clear definitions for readable and read/write span. + * SpanProcessors must provide read/write access at least in OnStart. ## v0.5.0 (06-02-2020) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0ac5dc2232c..a9d0a8762f8 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -160,9 +160,26 @@ Note: Implementation-wise, this could mean that `Tracer` instances have a reference to their `TracerProvider` and access configuration only via this reference. -The readable representations of all `Span` instances created by a `Tracer` must -provide a `getInstrumentationLibrary` method that returns the -`InstrumentationLibrary` information held by the `Tracer`. +## Additional Span interfaces + +The [API-level definition for Span's interface](api.md#span-operations) +only defines write-only access to the Span. +This is good because instrumentations and applications are not to use the data +stored in a span for application logic. +However, the SDK needs to eventually read back the data in some locations. +Thus, the SDK specification defines two new terms: + +* **Readable span**: A span interface that MUST allow to retrieve all information + that was added to the span (e.g. all attributes, events, (parent) SpanContext, + etc.). + A readable span MAY be identical to a read/write span, i.e., SDKs are not + required to have a read-only interface. + SDKs are also allowed to use a read/write span instead of a different readable + only in some places where the SDK requires a readable span. +* **Read/write span**: A span that provides both the full API as defined in the + [API-level definition for Span's interface](api.md#span-operations) and + additionally the same interface as for Readable spans + as defined in the above bullet point. ## Span processor @@ -211,7 +228,7 @@ exceptions. **Parameters:** -* `Span` - a readable span object. +* `Span` - a [read/write span object](#additional-span-interfaces) for the started span. **Returns:** `Void` @@ -222,7 +239,11 @@ the execution thread, therefore it should not block or throw an exception. **Parameters:** -* `Span` - a readable span object. +* `Span` - a [readable span object](#additional-span-interfaces) for the started span. + Note: Since multiple SpanProcessors may be involved, and OnEnd is typically used + for sending data to exporters, SpanProcessors should rather not modify spans + in `OnEnd`, since the resulting behavior would be sensitive to the order of + `SpanProcessors`'s `OnEnd` calls. **Returns:** `Void` @@ -298,7 +319,8 @@ interfaces, one that accepts spans (SpanExporter) and one that accepts metrics #### `Export(batch)` -Exports a batch of telemetry data. Protocol exporters that will implement this +Exports a batch of [readable spans](#additional-span-interfaces). +Protocol exporters that will implement this function are typically expected to serialize and transmit the data to the destination. @@ -316,14 +338,8 @@ and backend the spans are being sent to. **Parameters:** batch - a batch of telemetry data. The exact data type of the batch is language -specific, typically it is a list of telemetry items, e.g. for spans in Java it -will be typically `Collection`. - -Note that the data type for a span for illustration purposes here is written as -an imaginary type ExportableSpan (similarly for metrics it would be e.g. -ExportableMetrics). The actual data type must be specified by language library -authors, it should be able to represent the span data that can be read by the -exporter. +specific, typically it is a list of [readable spans](#additional-span-interfaces), +e.g. for spans in Java it will be typically `Collection`. **Returns:** ExportResult: From 31e8f374ff0be9340b57412840d9487726ba6cf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 11:25:03 +0200 Subject: [PATCH 02/14] Typo --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index a9d0a8762f8..8467181bea7 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -174,7 +174,7 @@ Thus, the SDK specification defines two new terms: etc.). A readable span MAY be identical to a read/write span, i.e., SDKs are not required to have a read-only interface. - SDKs are also allowed to use a read/write span instead of a different readable + SDKs are also allowed to use a read/write span instead of a different readable interface only in some places where the SDK requires a readable span. * **Read/write span**: A span that provides both the full API as defined in the [API-level definition for Span's interface](api.md#span-operations) and From 86d26a2fe5c4911574ab776f6a38fd928a72f5a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 11:30:34 +0200 Subject: [PATCH 03/14] Formatting. --- specification/trace/sdk.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 8467181bea7..203d857d479 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -163,21 +163,21 @@ reference. ## Additional Span interfaces The [API-level definition for Span's interface](api.md#span-operations) -only defines write-only access to the Span. +only defines write-only access to the span. This is good because instrumentations and applications are not to use the data stored in a span for application logic. However, the SDK needs to eventually read back the data in some locations. Thus, the SDK specification defines two new terms: * **Readable span**: A span interface that MUST allow to retrieve all information - that was added to the span (e.g. all attributes, events, (parent) SpanContext, + that was added to the span (e.g. all attributes, events, (parent) `SpanContext`, etc.). A readable span MAY be identical to a read/write span, i.e., SDKs are not required to have a read-only interface. SDKs are also allowed to use a read/write span instead of a different readable interface only in some places where the SDK requires a readable span. * **Read/write span**: A span that provides both the full API as defined in the - [API-level definition for Span's interface](api.md#span-operations) and + [API-level definition for span's interface](api.md#span-operations) and additionally the same interface as for Readable spans as defined in the above bullet point. From 91eafdcf529df52faf6c721d466a0bdd7a970a35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 11:39:32 +0200 Subject: [PATCH 04/14] Typo. --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 203d857d479..c92b2e5cfdb 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -178,7 +178,7 @@ Thus, the SDK specification defines two new terms: only in some places where the SDK requires a readable span. * **Read/write span**: A span that provides both the full API as defined in the [API-level definition for span's interface](api.md#span-operations) and - additionally the same interface as for Readable spans + additionally the same interface as for readable spans as defined in the above bullet point. ## Span processor From 9a11b7646f04dfa66e34f7ba82dc042c5e4da331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 12:07:31 +0200 Subject: [PATCH 05/14] Wording improvements. Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 +- specification/trace/sdk.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 33ad995f2aa..a60b7e33f2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ the release. - Clarify Tracer vs TracerProvider in tracing API and SDK spec. Most importantly: * Configuration should be stored not per Tracer but in the TracerProvider. * Active spans are not per Tracer. -- Provide clear definitions for readable and read/write span. +- Provide clear definitions for readable and read/write span interfaces in the SDK. * SpanProcessors must provide read/write access at least in OnStart. ## v0.5.0 (06-02-2020) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index c92b2e5cfdb..ff2075e2488 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -164,7 +164,7 @@ reference. The [API-level definition for Span's interface](api.md#span-operations) only defines write-only access to the span. -This is good because instrumentations and applications are not to use the data +This is good because instrumentations and applications are not meant to use the data stored in a span for application logic. However, the SDK needs to eventually read back the data in some locations. Thus, the SDK specification defines two new terms: @@ -242,7 +242,7 @@ the execution thread, therefore it should not block or throw an exception. * `Span` - a [readable span object](#additional-span-interfaces) for the started span. Note: Since multiple SpanProcessors may be involved, and OnEnd is typically used for sending data to exporters, SpanProcessors should rather not modify spans - in `OnEnd`, since the resulting behavior would be sensitive to the order of + in `OnEnd`, even if the passed object would allow this, since the resulting behavior would be sensitive to the order of `SpanProcessors`'s `OnEnd` calls. **Returns:** `Void` @@ -339,7 +339,7 @@ and backend the spans are being sent to. batch - a batch of telemetry data. The exact data type of the batch is language specific, typically it is a list of [readable spans](#additional-span-interfaces), -e.g. for spans in Java it will be typically `Collection`. +e.g. for spans in Java it will be typically `Collection`. **Returns:** ExportResult: From b59b69ab6aca1a5fd1b056bfbc1ce6595d92b71f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 12:08:14 +0200 Subject: [PATCH 06/14] Fix accidentally removed wording for InstrumentationLibrary Co-authored-by: Armin Ruech --- specification/trace/sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index ff2075e2488..19b022e555d 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -172,6 +172,8 @@ Thus, the SDK specification defines two new terms: * **Readable span**: A span interface that MUST allow to retrieve all information that was added to the span (e.g. all attributes, events, (parent) `SpanContext`, etc.). + The readable span MUST provide a method called `getInstrumentationLibrary` (or similar), + that returns the `InstrumentationLibrary` information held by the `Tracer` that created the span. A readable span MAY be identical to a read/write span, i.e., SDKs are not required to have a read-only interface. SDKs are also allowed to use a read/write span instead of a different readable interface From 14a5a170174da5187b5fc656b8c9b4d731706486 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 24 Jun 2020 12:15:00 +0200 Subject: [PATCH 07/14] More wording improvements. --- specification/trace/sdk.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 19b022e555d..fbcebf1e36b 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -172,16 +172,18 @@ Thus, the SDK specification defines two new terms: * **Readable span**: A span interface that MUST allow to retrieve all information that was added to the span (e.g. all attributes, events, (parent) `SpanContext`, etc.). + The readable span MUST provide a method called `getInstrumentationLibrary` (or similar), that returns the `InstrumentationLibrary` information held by the `Tracer` that created the span. - A readable span MAY be identical to a read/write span, i.e., SDKs are not - required to have a read-only interface. - SDKs are also allowed to use a read/write span instead of a different readable interface - only in some places where the SDK requires a readable span. * **Read/write span**: A span that provides both the full API as defined in the [API-level definition for span's interface](api.md#span-operations) and additionally the same interface as for readable spans as defined in the above bullet point. + +The readable span interface MAY be identical to the read/write interface, +i.e., SDKs are not required to have a read-only interface. +SDKs are also allowed to use a read/write span instead of a different readable interface +only in some places where the SDK requires a readable span. ## Span processor @@ -339,8 +341,8 @@ and backend the spans are being sent to. **Parameters:** -batch - a batch of telemetry data. The exact data type of the batch is language -specific, typically it is a list of [readable spans](#additional-span-interfaces), +batch - a batch of [readable spans](#additional-span-interfaces). The exact data type of the batch is language +specific, typically it is some kind of list, e.g. for spans in Java it will be typically `Collection`. **Returns:** ExportResult: From 6bc4531e2f6e8cc6b1b31f9a574628969bad6cf7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 7 Jul 2020 16:10:50 +0200 Subject: [PATCH 08/14] Specify that OnEnd is called after ending the span. --- specification/trace/sdk.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 27726e435b9..c023704886a 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -175,7 +175,7 @@ Thus, the SDK specification defines two new terms: The readable span MUST provide a method called `getInstrumentationLibrary` (or similar), that returns the `InstrumentationLibrary` information held by the `Tracer` that created the span. -* **Read/write span**: A span that provides both the full API as defined in the +* **Read/write span**: A span that provides both the full span API as defined in the [API-level definition for span's interface](api.md#span-operations) and additionally the same interface as for readable spans as defined in the above bullet point. @@ -238,16 +238,15 @@ exceptions. #### OnEnd(Span) -`OnEnd` is called when a span is ended. This method is called synchronously on -the execution thread, therefore it should not block or throw an exception. +`OnEnd` is called after a span is ended (i.e., the end timestamp is already set). +This method MUST be called synchronously within the [`Span.End()` API](api.md#end), +therefore it should not block or throw an exception. **Parameters:** -* `Span` - a [readable span object](#additional-span-interfaces) for the started span. - Note: Since multiple SpanProcessors may be involved, and OnEnd is typically used - for sending data to exporters, SpanProcessors should rather not modify spans - in `OnEnd`, even if the passed object would allow this, since the resulting behavior would be sensitive to the order of - `SpanProcessors`'s `OnEnd` calls. +* `Span` - a [readable span object](#additional-span-interfaces) for the ended span. + Note: Even if the passed Span may be technically writable, + since it's already ended at this point, modifying it is not allowed. **Returns:** `Void` From 6ea40672a9a3e774f0f580684f723dc5d2b43a7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 7 Jul 2020 16:16:29 +0200 Subject: [PATCH 09/14] Update TOC. --- specification/trace/sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index c023704886a..16267d79ec0 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -6,6 +6,7 @@ * [Sampling](#sampling) * [Tracer Creation](#tracer-creation) +* [Additional Span Interfaces](#additional-span-interfaces) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) @@ -160,7 +161,7 @@ Note: Implementation-wise, this could mean that `Tracer` instances have a reference to their `TracerProvider` and access configuration only via this reference. -## Additional Span interfaces +## Additional Span Interfaces The [API-level definition for Span's interface](api.md#span-operations) only defines write-only access to the span. From 59fb611023f72b76ead3a7184a2337bca314017d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 7 Jul 2020 16:18:00 +0200 Subject: [PATCH 10/14] Wording. --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 16267d79ec0..7fc664c16db 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -184,7 +184,7 @@ Thus, the SDK specification defines two new terms: The readable span interface MAY be identical to the read/write interface, i.e., SDKs are not required to have a read-only interface. SDKs are also allowed to use a read/write span instead of a different readable interface -only in some places where the SDK requires a readable span. +only in some places where the specification requires a readable span. ## Span processor From c9a5d44fcb880fc559e9c80ee13646f616ec811d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 7 Jul 2020 18:48:10 +0200 Subject: [PATCH 11/14] Try to clarify abstractness of readable and read-write requirements. --- specification/trace/sdk.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 7fc664c16db..1d9f10d7f64 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -170,21 +170,27 @@ stored in a span for application logic. However, the SDK needs to eventually read back the data in some locations. Thus, the SDK specification defines two new terms: -* **Readable span**: A span interface that MUST allow to retrieve all information +* **Readable span**: A span interface satisfies the requirements of being a + readable span if it allows to retrieve all information that was added to the span (e.g. all attributes, events, (parent) `SpanContext`, etc.). - The readable span MUST provide a method called `getInstrumentationLibrary` (or similar), + A readable span interface MUST provide a method called `getInstrumentationLibrary` (or similar), that returns the `InstrumentationLibrary` information held by the `Tracer` that created the span. -* **Read/write span**: A span that provides both the full span API as defined in the +* **Read/write span**: A span interface satisfies this requirement of being a + read/write span if it provides both the full span API as defined in the [API-level definition for span's interface](api.md#span-operations) and - additionally the same interface as for readable spans + additionally satisfies the requirements for being a readable span as defined in the above bullet point. -The readable span interface MAY be identical to the read/write interface, -i.e., SDKs are not required to have a read-only interface. -SDKs are also allowed to use a read/write span instead of a different readable interface -only in some places where the specification requires a readable span. +Note: First, these requirements use "interface" in the most abstract sense -- +it does not need to be an actual Java `interface` for example but could also be +a `final` POJO. Second, these are abstract requirements for interfaces. Not all +places in the spec that talk about a readable span need to be implemented by the +same concrete interface. For example, this allows using a different interface +for the readable span passed to an exporter than for the readable span passed +to a SpanProcessor's OnEnd. On the other hand, +it allows implementing a readable span as a read/write span. ## Span processor From 179fcc17d24fbf26cff647abc9a8e412e5877e4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 20 Jul 2020 15:32:09 +0200 Subject: [PATCH 12/14] Revert accidental change to CHANGELOG. --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec57269c3dc..9335557c1ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,6 @@ the release. ## Unreleased - New: - Add resource semantic conventions for operating systems ([#693](https://github.com/open-telemetry/opentelemetry-specification/pull/693)) From 0b9709d6e61bd4b4353a933af30d4be1bd340e5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 22 Jul 2020 10:49:18 +0200 Subject: [PATCH 13/14] "interface" is really in the *most* abstract sense --- specification/trace/sdk.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index b3b8d987b9d..e107f23cd00 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -177,7 +177,13 @@ Thus, the SDK specification defines two new terms: Note: First, these requirements use "interface" in the most abstract sense -- it does not need to be an actual Java `interface` for example but could also be -a `final` POJO. Second, these are abstract requirements for interfaces. Not all +a `final` POJO, or, especially in the case of read/write span, even two (or more) +separate objects that are passed together to give full read/write capabilities +(when chosing this implemenation technique, +changes through one object should be reflected in the other +objects immediately if they are observable through them at all +to avoid introducing suble gotchas). +Second, these are abstract requirements for interfaces. Not all places in the spec that talk about a readable span need to be implemented by the same concrete interface. For example, this allows using a different interface for the readable span passed to an exporter than for the readable span passed From 3866bb147da6549bfe6b3b3ad02d0409bf6b8ba4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 29 Jul 2020 18:18:44 +0200 Subject: [PATCH 14/14] Typo. Co-authored-by: Armin Ruech --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index e107f23cd00..1a84411b391 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -182,7 +182,7 @@ separate objects that are passed together to give full read/write capabilities (when chosing this implemenation technique, changes through one object should be reflected in the other objects immediately if they are observable through them at all -to avoid introducing suble gotchas). +to avoid introducing subtle gotchas). Second, these are abstract requirements for interfaces. Not all places in the spec that talk about a readable span need to be implemented by the same concrete interface. For example, this allows using a different interface