From 6487af5652172ce7c5c4146165e8c4d36fa0e3de Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 29 Jun 2021 14:44:10 -0700 Subject: [PATCH 1/5] Add context propagation requriements to HTTP conventions --- CHANGELOG.md | 3 +++ specification/trace/semantic_conventions/http.md | 6 ++++++ 2 files changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b40bd7bbd3..52279ca5f2b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,9 @@ release. - Remove `rpc.jsonrpc.method`, clarify that `rpc.method` should be used instead. ([#1748](https://github.com/open-telemetry/opentelemetry-specification/pull/1748)) +- Add context propagation requirements to HTTP spec. + ([TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) + ### Compatibility ### OpenTelemetry Protocol diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 45d19180f8e..0ec0b4bfee8 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -15,6 +15,7 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Status](#status) - [Common Attributes](#common-attributes) - [HTTP client](#http-client) + - [Context propagation](#context-propagation) - [HTTP server](#http-server) - [HTTP server definitions](#http-server-definitions) - [HTTP Server semantic conventions](#http-server-semantic-conventions) @@ -111,6 +112,11 @@ from the `net.peer.name` used to look up the `net.peer.ip` that is actually connected to. In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`. +### Context propagation + +- context created for HTTP client span MUST be injected on outgoing request using configured [propagator](../../context/api-propagators.md) +- if outgoing HTTP request already has context (for configured propagator) injected, it cannot be changed and new span MUST not be created + ## HTTP server To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection. From d40ab599c50c1afe2cc6c75e4e648b4c3f65f1fe Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 29 Jun 2021 15:10:44 -0700 Subject: [PATCH 2/5] changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52279ca5f2b..4ed34263879 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,7 +28,7 @@ release. ([#1748](https://github.com/open-telemetry/opentelemetry-specification/pull/1748)) - Add context propagation requirements to HTTP spec. - ([TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) + ([#1783](https://github.com/open-telemetry/opentelemetry-specification/pull/1783)) ### Compatibility From 71d620c77e24a2fdd8e434ab309e0db758461267 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 30 Jun 2021 20:06:21 -0700 Subject: [PATCH 3/5] add examples --- CHANGELOG.md | 1 - .../trace/semantic_conventions/http.md | 26 +++++++++++++++++-- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ed34263879..9b8e39a3ff1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,7 +26,6 @@ release. - Remove `rpc.jsonrpc.method`, clarify that `rpc.method` should be used instead. ([#1748](https://github.com/open-telemetry/opentelemetry-specification/pull/1748)) - - Add context propagation requirements to HTTP spec. ([#1783](https://github.com/open-telemetry/opentelemetry-specification/pull/1783)) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 0ec0b4bfee8..4666f13b4ef 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -16,6 +16,8 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Common Attributes](#common-attributes) - [HTTP client](#http-client) - [Context propagation](#context-propagation) + - [Example 1: context propagation](#example-1-context-propagation) + - [Example 2: back-off](#example-2-back-off) - [HTTP server](#http-server) - [HTTP server definitions](#http-server-definitions) - [HTTP Server semantic conventions](#http-server-semantic-conventions) @@ -114,8 +116,28 @@ In that case it is strongly recommended to set the `net.peer.name` attribute in ### Context propagation -- context created for HTTP client span MUST be injected on outgoing request using configured [propagator](../../context/api-propagators.md) -- if outgoing HTTP request already has context (for configured propagator) injected, it cannot be changed and new span MUST not be created +- context created for HTTP client span (if valid) MUST be injected on outgoing request header using configured [propagator](../../context/api-propagators.md) +- Exception: if outgoing HTTP request already has valid context (for configured propagator), it cannot be changed and new span MUST NOT be recorded + +#### Example 1: context propagation + +No existing valid context, W3C Trace-Context propagator + +1. Instrumentation checks if valid context can be extracted + - no, there is no W3C Trace-Context + - OR: yes, there is an invalid context + - OR: yes, there is a valid B3 context +2. Instrumentation starts a span +3. Instrumentation injects context of the new span using W3C propagator +4. Instrumentation waits for call to complete and ends span + +#### Example 2: back-off + +Existing valid context, W3C Trace-Context propagator + +1. Instrumentation checks if valid context can be extracted using W3C propagator + - yes, there is a valid W3C Trace-Context +2. Instrumentation lets call to complete without creating a span ## HTTP server From ee9d872faa63b2bb605269a279df098c651543a6 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 30 Jun 2021 20:16:36 -0700 Subject: [PATCH 4/5] up --- .../trace/semantic_conventions/http.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 4666f13b4ef..92b931f935a 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -121,22 +121,21 @@ In that case it is strongly recommended to set the `net.peer.name` attribute in #### Example 1: context propagation -No existing valid context, W3C Trace-Context propagator +There is no valid W3C Trace Context on the request when instrumentation starts, W3C Trace Context propagator is configured on the instrumentation. -1. Instrumentation checks if valid context can be extracted - - no, there is no W3C Trace-Context - - OR: yes, there is an invalid context - - OR: yes, there is a valid B3 context +1. Instrumentation checks if a valid context can be extracted using W3C Trace-Context propagator + - no, there is no W3C Trace Context + - OR: yes, there is an invalid W3C Trace Context 2. Instrumentation starts a span -3. Instrumentation injects context of the new span using W3C propagator +3. Instrumentation injects context of the new span using the W3C Trace Context propagator 4. Instrumentation waits for call to complete and ends span #### Example 2: back-off -Existing valid context, W3C Trace-Context propagator +There is valid W3C Trace Context context on the request when instrumentation starts. W3C Trace Context propagator is configured on the instrumentation. -1. Instrumentation checks if valid context can be extracted using W3C propagator - - yes, there is a valid W3C Trace-Context +1. Instrumentation checks if valid context can be extracted using W3C Trace Context propagator + - yes, there is a valid W3C Trace Context 2. Instrumentation lets call to complete without creating a span ## HTTP server From ff8638082138cf3df291dd44e4a9e4da07de2086 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 8 Jul 2021 18:47:35 -0700 Subject: [PATCH 5/5] instrumentation that injects http header must also emit http span --- specification/trace/semantic_conventions/http.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 92b931f935a..d8ba321d9b6 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -116,8 +116,9 @@ In that case it is strongly recommended to set the `net.peer.name` attribute in ### Context propagation -- context created for HTTP client span (if valid) MUST be injected on outgoing request header using configured [propagator](../../context/api-propagators.md) -- Exception: if outgoing HTTP request already has valid context (for configured propagator), it cannot be changed and new span MUST NOT be recorded +`Context` created for HTTP client span (if valid) MUST be injected on outgoing request headers using configured [propagator](../../context/api-propagators.md). Instrumentation that injects `Context` into HTTP request headers MUST also emit a span that complies with other client requirements in this specification. + +**Exception**: if outgoing HTTP request already has valid `Context` (for configured propagator), it cannot be changed and new span MUST NOT be recorded. #### Example 1: context propagation