From d693fb91962efe27ac10a071514bd7815b67cde5 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Sep 2020 04:34:24 +0000 Subject: [PATCH 01/17] note on default propagators --- specification/context/api-propagators.md | 25 ++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 654dd21e88c..341a79a0318 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -267,14 +267,23 @@ Required arguments: ## Global Propagators -Implementations MAY provide global `Propagator`s for -each supported `Propagator` type. - -If offered, the global `Propagator`s should default to a composite `Propagator` -containing the W3C Trace Context Propagator and the Baggage `Propagator` -specified in [api-baggage.md](../baggage/api.md#serialization), -in order to provide propagation even in the presence of no-op -OpenTelemetry implementations. +OpenTelemetry API should provide a way to obtain a propagator for each supported +`Propagator` type. Instrumentation library SHOULD call propagators to extract +and inject context on all remote calls. Propagators depending on the language +MAY be set up using various dependency injection techniques or available as +global accessors. + +**Note:** it is discouraged practice, but certain instrumentation libraries +might use proprietary context propagation protocols or default into a specific +one. In such cases, instrumentation library MAY choose not to call use supplied +propagators and instead hardcode the context extract and inject logic. + +OpenTelemetry API MUST use no-op propagators when used unconfigured. Context +propagation may be used for various telemetry signals - traces, metrics, logging +and more. Platforms such as ASP.NET may pre-configure out-of-the-box +propagators. If pre-configured, `Propagator`s SHOULD default to a composite +`Propagator` containing the W3C Trace Context Propagator and the Baggage +`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). Platform MUST also allow to disable pre-configured propagators. ### Get Global Propagator From 5a86d557f2dbafeb27bae3db9b841be6aff84f9c Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Sep 2020 04:37:42 +0000 Subject: [PATCH 02/17] changelog update --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d96cd1ef85..50904a89961 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ release. New: +- Default propagators in un-configured API must be no-op + ([#next](https://github.com/open-telemetry/opentelemetry-specification/pull/next)). - Define resource mapping for Jaeger exporters ([#891](https://github.com/open-telemetry/opentelemetry-specification/pull/891)) - Add resource semantic conventions for operating systems From 1068789a4f74118ff7c21fe008ebd9009ed00bf4 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Sep 2020 04:39:00 +0000 Subject: [PATCH 03/17] pr number --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 50904a89961..b0bf93494ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ release. New: - Default propagators in un-configured API must be no-op - ([#next](https://github.com/open-telemetry/opentelemetry-specification/pull/next)). + ([#930](https://github.com/open-telemetry/opentelemetry-specification/pull/930)). - Define resource mapping for Jaeger exporters ([#891](https://github.com/open-telemetry/opentelemetry-specification/pull/891)) - Add resource semantic conventions for operating systems From c1163f04295706718f943e9a2e78749a59ac382e Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Sep 2020 20:11:37 +0000 Subject: [PATCH 04/17] addressed PR feedback --- specification/context/api-propagators.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 341a79a0318..596e9b9967a 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -274,13 +274,17 @@ MAY be set up using various dependency injection techniques or available as global accessors. **Note:** it is discouraged practice, but certain instrumentation libraries -might use proprietary context propagation protocols or default into a specific -one. In such cases, instrumentation library MAY choose not to call use supplied -propagators and instead hardcode the context extract and inject logic. +might use proprietary context propagation protocols or be hardcoded to use a +specific one. In such cases, instrumentation library MAY choose not to use the +API-provided propagators and instead hardcode the context extract and inject +logic. OpenTelemetry API MUST use no-op propagators when used unconfigured. Context propagation may be used for various telemetry signals - traces, metrics, logging -and more. Platforms such as ASP.NET may pre-configure out-of-the-box +and more. So context propagation MAY be enabled for any of them. For instance, +trace exporter may not be configured while trace context is propagated. + +Platforms such as ASP.NET may pre-configure out-of-the-box propagators. If pre-configured, `Propagator`s SHOULD default to a composite `Propagator` containing the W3C Trace Context Propagator and the Baggage `Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). Platform MUST also allow to disable pre-configured propagators. From 8c780e3f0fd5caad263e31e29b58dd693019ea7a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:05:49 -0700 Subject: [PATCH 05/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 596e9b9967a..bd70f862d08 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -287,7 +287,7 @@ trace exporter may not be configured while trace context is propagated. Platforms such as ASP.NET may pre-configure out-of-the-box propagators. If pre-configured, `Propagator`s SHOULD default to a composite `Propagator` containing the W3C Trace Context Propagator and the Baggage -`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). Platform MUST also allow to disable pre-configured propagators. +`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). These platforms MUST also allow pre-configured propagators to be disabled. ### Get Global Propagator From 21661b02fa8f1c91b968f29e2183c30d59982e3a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:01 -0700 Subject: [PATCH 06/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index bd70f862d08..de191d3fc52 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -282,7 +282,7 @@ logic. OpenTelemetry API MUST use no-op propagators when used unconfigured. Context propagation may be used for various telemetry signals - traces, metrics, logging and more. So context propagation MAY be enabled for any of them. For instance, -trace exporter may not be configured while trace context is propagated. +a span exporter may be left unconfigured, although the trace context is being propagated. Platforms such as ASP.NET may pre-configure out-of-the-box propagators. If pre-configured, `Propagator`s SHOULD default to a composite From 07beb2bfd3a10071c3d78a1e8e2dd676ab378545 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:08 -0700 Subject: [PATCH 07/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index de191d3fc52..95f9412de8a 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -279,7 +279,7 @@ specific one. In such cases, instrumentation library MAY choose not to use the API-provided propagators and instead hardcode the context extract and inject logic. -OpenTelemetry API MUST use no-op propagators when used unconfigured. Context +The OpenTelemetry API MUST use no-op propagators when used unconfigured. Context propagation may be used for various telemetry signals - traces, metrics, logging and more. So context propagation MAY be enabled for any of them. For instance, a span exporter may be left unconfigured, although the trace context is being propagated. From 0d5874cb69e4eaea1ce5d379f36351a8a35f04a3 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:15 -0700 Subject: [PATCH 08/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 95f9412de8a..774ea4847c2 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -281,7 +281,7 @@ logic. The OpenTelemetry API MUST use no-op propagators when used unconfigured. Context propagation may be used for various telemetry signals - traces, metrics, logging -and more. So context propagation MAY be enabled for any of them. For instance, +and more. Therefore, context propagation MAY be enabled for any of them. For instance, a span exporter may be left unconfigured, although the trace context is being propagated. Platforms such as ASP.NET may pre-configure out-of-the-box From 7d7373d9ef2b567532438f8f43d4a880db2923bb Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:22 -0700 Subject: [PATCH 09/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 774ea4847c2..e5d79685954 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -276,7 +276,7 @@ global accessors. **Note:** it is discouraged practice, but certain instrumentation libraries might use proprietary context propagation protocols or be hardcoded to use a specific one. In such cases, instrumentation library MAY choose not to use the -API-provided propagators and instead hardcode the context extract and inject +API-provided propagators and instead hardcode the context extraction and injection logic. The OpenTelemetry API MUST use no-op propagators when used unconfigured. Context From be8db72dc83933b0cde9ccac51b296f76102e31c Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:28 -0700 Subject: [PATCH 10/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index e5d79685954..820604f518f 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -275,7 +275,7 @@ global accessors. **Note:** it is discouraged practice, but certain instrumentation libraries might use proprietary context propagation protocols or be hardcoded to use a -specific one. In such cases, instrumentation library MAY choose not to use the +specific one. In such cases, instrumentation libraries MAY choose not to use the API-provided propagators and instead hardcode the context extraction and injection logic. From 5e5e396ee0868e1db2caecbe48e88e06b97bdce7 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:35 -0700 Subject: [PATCH 11/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 820604f518f..01fb68dd7e4 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -273,7 +273,7 @@ and inject context on all remote calls. Propagators depending on the language MAY be set up using various dependency injection techniques or available as global accessors. -**Note:** it is discouraged practice, but certain instrumentation libraries +**Note:** it is a discouraged practice, but certain instrumentation libraries might use proprietary context propagation protocols or be hardcoded to use a specific one. In such cases, instrumentation libraries MAY choose not to use the API-provided propagators and instead hardcode the context extraction and injection From 8291c189f06176f649af335f29a13e414cf5a7c2 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:42 -0700 Subject: [PATCH 12/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 01fb68dd7e4..8866c16bf7f 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -269,7 +269,7 @@ Required arguments: OpenTelemetry API should provide a way to obtain a propagator for each supported `Propagator` type. Instrumentation library SHOULD call propagators to extract -and inject context on all remote calls. Propagators depending on the language +and inject the context on all remote calls. Propagators, depending on the language, MAY be set up using various dependency injection techniques or available as global accessors. From 8fb1886835912ec855734dd8e70b0ea27ccb22dc Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:48 -0700 Subject: [PATCH 13/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 8866c16bf7f..794b76b2b03 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -268,7 +268,7 @@ Required arguments: ## Global Propagators OpenTelemetry API should provide a way to obtain a propagator for each supported -`Propagator` type. Instrumentation library SHOULD call propagators to extract +`Propagator` type. Instrumentation libraries SHOULD call propagators to extract and inject the context on all remote calls. Propagators, depending on the language, MAY be set up using various dependency injection techniques or available as global accessors. From ff6c08da0ef8e815bf67f56a455ee88956072260 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 11 Sep 2020 00:06:55 -0700 Subject: [PATCH 14/17] Update specification/context/api-propagators.md Co-authored-by: John Watson --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 794b76b2b03..56460b2b048 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -267,7 +267,7 @@ Required arguments: ## Global Propagators -OpenTelemetry API should provide a way to obtain a propagator for each supported +The OpenTelemetry API should provide a way to obtain a propagator for each supported `Propagator` type. Instrumentation libraries SHOULD call propagators to extract and inject the context on all remote calls. Propagators, depending on the language, MAY be set up using various dependency injection techniques or available as From 3840f9d0e387e9d3f0d8ebe93695c2e149d6003a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 16 Sep 2020 17:35:22 +0000 Subject: [PATCH 15/17] a few clarificaiton to address PR review --- specification/context/api-propagators.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 56460b2b048..3243471040f 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -267,11 +267,11 @@ Required arguments: ## Global Propagators -The OpenTelemetry API should provide a way to obtain a propagator for each supported -`Propagator` type. Instrumentation libraries SHOULD call propagators to extract -and inject the context on all remote calls. Propagators, depending on the language, -MAY be set up using various dependency injection techniques or available as -global accessors. +The OpenTelemetry API MUST provide a way to obtain a propagator for each +supported `Propagator` type. Instrumentation libraries SHOULD call propagators +to extract and inject the context on all remote calls. Propagators, depending on +the language, MAY be set up using various dependency injection techniques or +available as global accessors. **Note:** it is a discouraged practice, but certain instrumentation libraries might use proprietary context propagation protocols or be hardcoded to use a @@ -279,15 +279,16 @@ specific one. In such cases, instrumentation libraries MAY choose not to use the API-provided propagators and instead hardcode the context extraction and injection logic. -The OpenTelemetry API MUST use no-op propagators when used unconfigured. Context -propagation may be used for various telemetry signals - traces, metrics, logging -and more. Therefore, context propagation MAY be enabled for any of them. For instance, -a span exporter may be left unconfigured, although the trace context is being propagated. +The OpenTelemetry API MUST use no-op propagators unless explicitly configured +otherwise. Context propagation may be used for various telemetry signals - +traces, metrics, logging and more. Therefore, context propagation MAY be enabled +for any of them independently. For instance, a span exporter may be left +unconfigured, although the trace context propagation was configured to enrich logs or metrics. Platforms such as ASP.NET may pre-configure out-of-the-box propagators. If pre-configured, `Propagator`s SHOULD default to a composite `Propagator` containing the W3C Trace Context Propagator and the Baggage -`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). These platforms MUST also allow pre-configured propagators to be disabled. +`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). These platforms MUST also allow pre-configured propagators to be disabled or overridden. ### Get Global Propagator From 3f44162b29d7fa8eb1e7704af50805334eb16713 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Thu, 17 Sep 2020 09:28:31 -0700 Subject: [PATCH 16/17] Update specification/context/api-propagators.md Co-authored-by: Armin Ruech --- specification/context/api-propagators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 3243471040f..45874637bbd 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -273,7 +273,7 @@ to extract and inject the context on all remote calls. Propagators, depending on the language, MAY be set up using various dependency injection techniques or available as global accessors. -**Note:** it is a discouraged practice, but certain instrumentation libraries +**Note:** It is a discouraged practice, but certain instrumentation libraries might use proprietary context propagation protocols or be hardcoded to use a specific one. In such cases, instrumentation libraries MAY choose not to use the API-provided propagators and instead hardcode the context extraction and injection From 270de4a7bcf1638245e71101458f7c7e0e9404f9 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Thu, 17 Sep 2020 09:28:57 -0700 Subject: [PATCH 17/17] Update specification/context/api-propagators.md Co-authored-by: Armin Ruech --- specification/context/api-propagators.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 45874637bbd..17aff8f1eb5 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -288,7 +288,8 @@ unconfigured, although the trace context propagation was configured to enrich lo Platforms such as ASP.NET may pre-configure out-of-the-box propagators. If pre-configured, `Propagator`s SHOULD default to a composite `Propagator` containing the W3C Trace Context Propagator and the Baggage -`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). These platforms MUST also allow pre-configured propagators to be disabled or overridden. +`Propagator` specified in [api-baggage.md](../baggage/api.md#serialization). +These platforms MUST also allow pre-configured propagators to be disabled or overridden. ### Get Global Propagator