From 1c9bc9d5263cea3ff6e650011be9428cb798f0c8 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 10 Aug 2020 03:42:04 +0200 Subject: [PATCH 1/8] Initial OpenTracing compatibility section. --- specification/opentracing-compatibility.md | 148 +++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 specification/opentracing-compatibility.md diff --git a/specification/opentracing-compatibility.md b/specification/opentracing-compatibility.md new file mode 100644 index 00000000000..56f41ab3518 --- /dev/null +++ b/specification/opentracing-compatibility.md @@ -0,0 +1,148 @@ +# OpenTracing Compatibility + +
+Table of Contents + +* [Abstract](#abstract) +* [OpenTracing Tracer](#opentracing-tracer) + * [Create a Tracer shim](#create-a-tracer-shim) + * [Inject](#inject) + * [Extract](#extract) +* [Scope Manager](#scope-manager) + * [Activate a Span](#active-a-span) + * [Get the active Span](#get-the-active-span) +* [Span](#span) + * [Get Context](#get-context) + * [Get Baggage Item](#get-baggage-item) + * [Set Baggage Item](#set-baggage-item) + * [Set Tag](#set-tag) + * [Log](#log) + * [Finish](#finish) + * [SpanContext](#spancontext) + * [Get Baggage Items](#get-baggage-items) + +
+ +## Abstract + +The OpenTelemetry project aims to provide backwards compatibility with the +[OpenTracing](https://opentracing.io) project in order ease migration of +instrumented codebases. + +This functionality will be provided as a bridge layer implementing the +[OpenTracing API](https://github.com/opentracing/specification) using the +OpenTelemetry API. This layer MUST NOT rely on implementation specific details +of any SDK. + +## OpenTracing Tracer + +The OpenTracing Tracer operations MUST be implemented using the OpenTelemetry +API: + +- An OpenTelemetry `Tracer` MUST be used to create `Span`s. +- A `CorrelationContextManager` MUST be used to create the `CorrelationContext` + objects used to implement the OpenTracing `Span` baggage. +- A `Propagator` MUST be used in order to perform inject and extract operations. + +### Create a Tracer Shim + +The operation MUST accept the following parameters: + +- An OpenTelemetry `Tracer`. +- A `CorrelationContextManager`. +- A list of `Propagator`s of the supported types, usually `Composite Propagator`s. + +The API MUST return an OpenTracing `Tracer`. + +### Inject + +Inject the underlying `SpanContext` using the registered `Propagator`s: + +- `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. + +Errors MUST NOT raised if the specified OpenTracing `Format` is not supported. + +### Extract + +Extract an OpenTelemetry `SpanContext` from a carrier using the registered `Propagator`s: + +- `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. + +Returns an OpenTracing `SpanContext` with the underlying extracted `SpanContext`, or null if +either the OpenTracing `Format` is not supported or no value could be extracted. + +## ScopeManager. + +For OpenTracing languages implementing the `ScopeManager` interface, its operations +MUST be implemented using the OpenTelemetry context propagation API. + +### Activate a Span. + +Sets the specified `Span` as active for the current `Context`. + +### Get the active Span. + +Gets the active `Span` for the current `Context`. The API MUST return +null if none exist. + +## Span + +The `Span` operations MUST be implemented using an underlying OpenTelemetry `Span` +in conjunction with an associated `CorrelationContext` object used to implement its +baggage part. + +OpenTracing `SpanContext` shim objects MUST act as objects associating an +underlying `SpanContext` with a `CorrelationContext`. Every invocation to the +`Set Baggage Item` operation will result in a newly associated `SpanContext` shim object +with a new `CorrelationContext` containing the specified name/value pair. + +Each underlying `Span` can only be associated with one `SpanContext` shim at a time +for all the execution units. + +The `Log` operations MUST be implemented using `Span`'s `Add Events`. + +The `Set Tag` operations MUST be implemented using `Span`'s `Set Attributes`. + +### Get Context + +Gets the currently associated `SpanContext` shim. + +### Get Baggage Item + +Gets a value for the specified name in the `CorrelationContext` of the associated `SpanContext` +shim or null if none exists. + +### Set Baggage Item + +Creates a newly associated `SpanContext` shim object with a new `CorrelationContext` +containing the specified name/value pair. + +### Set Tag + +Calls `Set Attribute` on the underlying `Span` with the specified name/value pair. + +If the type of the specified value is not supported, an error MUST be raised. + +### Log + +Calls `Add Event` on the underlying `Span`. + +Specifying an explicit timestamp is not supported, and an error MUST be raised. + +### Finish + +Calls `End` on the underlying `Span`. + +Specifying an explicit timestamp is not supported, and an error MUST be raised. + +### SpanContext + +The `SpanContext` interface MUST be implemented using a OpenTelemetry `SpanContext` +in conjuction with an associated `CorrelationContext`. + +Observe that the assigned `SpanContext` and `CorrelationContext` MUST be read-only +and MUST NOT change after creation. + +#### Get Baggage Items + +Returns a shim exposing the associated `CorrelationContext` values. From bcdfb0008efcc5ddb19316156ecf251179a784f0 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 10 Aug 2020 03:50:55 +0200 Subject: [PATCH 2/8] Fixes. --- specification/opentracing-compatibility.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/opentracing-compatibility.md b/specification/opentracing-compatibility.md index 56f41ab3518..e9679a867a3 100644 --- a/specification/opentracing-compatibility.md +++ b/specification/opentracing-compatibility.md @@ -8,8 +8,8 @@ * [Create a Tracer shim](#create-a-tracer-shim) * [Inject](#inject) * [Extract](#extract) -* [Scope Manager](#scope-manager) - * [Activate a Span](#active-a-span) +* [ScopeManager](#scopemanager) + * [Activate a Span](#activate-a-span) * [Get the active Span](#get-the-active-span) * [Span](#span) * [Get Context](#get-context) @@ -42,7 +42,7 @@ API: - An OpenTelemetry `Tracer` MUST be used to create `Span`s. - A `CorrelationContextManager` MUST be used to create the `CorrelationContext` objects used to implement the OpenTracing `Span` baggage. -- A `Propagator` MUST be used in order to perform inject and extract operations. +- A set of `Propagator` MUST be leveraged in order to perform inject and extract operations. ### Create a Tracer Shim @@ -50,7 +50,7 @@ The operation MUST accept the following parameters: - An OpenTelemetry `Tracer`. - A `CorrelationContextManager`. -- A list of `Propagator`s of the supported types, usually `Composite Propagator`s. +- A set of `Propagator`s of the supported types, usually `Composite Propagator`s. The API MUST return an OpenTracing `Tracer`. @@ -60,7 +60,7 @@ Inject the underlying `SpanContext` using the registered `Propagator`s: - `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. -Errors MUST NOT raised if the specified OpenTracing `Format` is not supported. +Errors MUST NOT be raised if the specified OpenTracing `Format` is not supported. ### Extract From 3195643e2a4f5415e2501d73f12b2f326df18cc4 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 10 Aug 2020 16:31:51 +0200 Subject: [PATCH 3/8] Fix typo. --- specification/opentracing-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/opentracing-compatibility.md b/specification/opentracing-compatibility.md index e9679a867a3..9fd3f25a3ee 100644 --- a/specification/opentracing-compatibility.md +++ b/specification/opentracing-compatibility.md @@ -138,7 +138,7 @@ Specifying an explicit timestamp is not supported, and an error MUST be raised. ### SpanContext The `SpanContext` interface MUST be implemented using a OpenTelemetry `SpanContext` -in conjuction with an associated `CorrelationContext`. +in conjunction with an associated `CorrelationContext`. Observe that the assigned `SpanContext` and `CorrelationContext` MUST be read-only and MUST NOT change after creation. From 92da36fd54e23c5c25ffee3969312744809ea99f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 12 Aug 2020 20:49:39 +0200 Subject: [PATCH 4/8] Apply feedback. --- specification/opentracing-compatibility.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/specification/opentracing-compatibility.md b/specification/opentracing-compatibility.md index 9fd3f25a3ee..c1394733dd8 100644 --- a/specification/opentracing-compatibility.md +++ b/specification/opentracing-compatibility.md @@ -60,7 +60,7 @@ Inject the underlying `SpanContext` using the registered `Propagator`s: - `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. -Errors MUST NOT be raised if the specified OpenTracing `Format` is not supported. +Errors MUST NOT be raised if the specified OpenTracing `Format` is `BINARY`. ### Extract @@ -69,7 +69,7 @@ Extract an OpenTelemetry `SpanContext` from a carrier using the registered `Prop - `TEXT_MAP` and `HTTP_HEADERS` formats MUST use the registered `HTTPTextPropagator`, if any. Returns an OpenTracing `SpanContext` with the underlying extracted `SpanContext`, or null if -either the OpenTracing `Format` is not supported or no value could be extracted. +either the OpenTracing `Format` is `BINARY` or no value could be extracted. ## ScopeManager. @@ -121,19 +121,23 @@ containing the specified name/value pair. Calls `Set Attribute` on the underlying `Span` with the specified name/value pair. -If the type of the specified value is not supported, an error MUST be raised. +If the type of the specified value is not supported, the value MUST NOT be set and +a warning SHOULD be generated following the [error handling](error-handling.md) +section. ### Log Calls `Add Event` on the underlying `Span`. -Specifying an explicit timestamp is not supported, and an error MUST be raised. +If an explicit timestamp is specified, it MUST be converted from microseconds +to nanoseconds. ### Finish Calls `End` on the underlying `Span`. -Specifying an explicit timestamp is not supported, and an error MUST be raised. +If an explicit timestamp is specified, it MUST be converted from microseconds +to nanoseconds. ### SpanContext From dd331ab0850fd091bfc7763e1e0fc5ccb8f97a1f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 12 Aug 2020 20:53:41 +0200 Subject: [PATCH 5/8] Fix typo. --- specification/opentracing-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/opentracing-compatibility.md b/specification/opentracing-compatibility.md index c1394733dd8..ee5db2f766a 100644 --- a/specification/opentracing-compatibility.md +++ b/specification/opentracing-compatibility.md @@ -26,7 +26,7 @@ ## Abstract The OpenTelemetry project aims to provide backwards compatibility with the -[OpenTracing](https://opentracing.io) project in order ease migration of +[OpenTracing](https://opentracing.io) project in order to ease migration of instrumented codebases. This functionality will be provided as a bridge layer implementing the From b944a2cc198050610a4edb30e398089b9f7d67b3 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 14 Aug 2020 13:32:34 +0200 Subject: [PATCH 6/8] Have the OT doc under a compatibility subdir. --- .../opentracing.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specification/{opentracing-compatibility.md => compatibility/opentracing.md} (100%) diff --git a/specification/opentracing-compatibility.md b/specification/compatibility/opentracing.md similarity index 100% rename from specification/opentracing-compatibility.md rename to specification/compatibility/opentracing.md From c6027ba4ae0c58e997310b4d807e51c83dea2a3d Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 17 Aug 2020 17:03:18 +0200 Subject: [PATCH 7/8] Apply feedback. --- specification/compatibility/opentracing.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index ee5db2f766a..45900d36985 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -121,23 +121,22 @@ containing the specified name/value pair. Calls `Set Attribute` on the underlying `Span` with the specified name/value pair. -If the type of the specified value is not supported, the value MUST NOT be set and -a warning SHOULD be generated following the [error handling](error-handling.md) -section. +If the type of the specified value is not supported, the value MUST be converted +to a string. ### Log Calls `Add Event` on the underlying `Span`. -If an explicit timestamp is specified, it MUST be converted from microseconds -to nanoseconds. +If an explicit timestamp is specified, a conversion MUST be done to match the OT and +OTel units. ### Finish Calls `End` on the underlying `Span`. -If an explicit timestamp is specified, it MUST be converted from microseconds -to nanoseconds. +If an explicit timestamp is specified, a conversion MUST be done to match the OT and +OTel units. ### SpanContext From 272198e00e54002a49462d0702cafcc859e4a925 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 17 Aug 2020 17:08:22 +0200 Subject: [PATCH 8/8] Remove the read-only restriction for SpanContext values. --- specification/compatibility/opentracing.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index 45900d36985..78bed1eb8e4 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -143,9 +143,6 @@ OTel units. The `SpanContext` interface MUST be implemented using a OpenTelemetry `SpanContext` in conjunction with an associated `CorrelationContext`. -Observe that the assigned `SpanContext` and `CorrelationContext` MUST be read-only -and MUST NOT change after creation. - #### Get Baggage Items Returns a shim exposing the associated `CorrelationContext` values.