diff --git a/CHANGELOG.md b/CHANGELOG.md index ea0ed01002e..4c23a1ebda0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,8 @@ release. ([#1781](https://github.com/open-telemetry/opentelemetry-specification/pull/1781)) - 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)) ### Compatibility diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 45d19180f8e..d8ba321d9b6 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -15,6 +15,9 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Status](#status) - [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) @@ -111,6 +114,31 @@ 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 (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 + +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 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 the W3C Trace Context propagator +4. Instrumentation waits for call to complete and ends span + +#### Example 2: back-off + +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 Trace Context propagator + - yes, there is a valid W3C Trace Context +2. Instrumentation lets call to complete without creating a span + ## HTTP server To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection.