From 92fa12a8629332c9d5074a01d8b5846e7fbb8637 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Mon, 6 Mar 2023 18:14:32 +0100 Subject: [PATCH 1/5] HTTP client span clarification --- .../trace/semantic_conventions/http.md | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 636683beeb0..4e64e3d9127 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -119,12 +119,19 @@ Users MAY explicitly configure instrumentations to capture them even though it i ## HTTP client -This span type represents an outbound HTTP request. +This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: -For an HTTP client span, `SpanKind` MUST be `Client`. +1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. + In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). + Instrumentations MAY emit a "logical" (encompassing) span that is a parent of all the resend attempt spans; + however, this span MUST NOT exhibit HTTP semantics. + +2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), + instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. + In this case, the `http.url` MUST be the originally requested URL, before any HTTP-redirects that may happen when executing the request. + The instrumentation MUST NOT set the `http.resend_count` attribute. -If set, `http.url` must be the originally requested URL, -before any HTTP-redirects that may happen when executing the request. +For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | @@ -165,13 +172,14 @@ Note that in some cases host and port identifiers in the `Host` header might be Retries and redirects cause more than one physical HTTP request to be sent. A request is resent when an HTTP client library sends more than one HTTP request to satisfy the same API call. This may happen due to following redirects, authorization challenges, 503 Server Unavailable, network issues, or any other. -A CLIENT span SHOULD be created for each one of these physical requests. -No span is created corresponding to the "logical" (encompassing) request. -Each time an HTTP request is resent, the `http.resend_count` attribute SHOULD be added to each repeated span -and set to the ordinal number of the request resend attempt. +Each time an HTTP request is resent, the `http.resend_count` attribute MUST be added to each repeated span and set to the ordinal number of the request resend attempt. + +See the examples for more details about: -See [examples](#http-client-retries-examples) for more details. +* [retrying a server error](#http-client-retries-examples), +* [redirects](#http-client-redirects-examples), +* [authorization](#http-client-authorization-retry-examples). ## HTTP server From 7684fb3a9e4d79febd04cbde5770fc98c4b779f5 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 7 Mar 2023 09:37:59 +0100 Subject: [PATCH 2/5] code review comment --- specification/trace/semantic_conventions/http.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 4e64e3d9127..183db6c30f7 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -123,8 +123,7 @@ This span type represents an outbound HTTP request. There are two ways this can 1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). - Instrumentations MAY emit a "logical" (encompassing) span that is a parent of all the resend attempt spans; - however, this span MUST NOT exhibit HTTP semantics. + In this case, instrumentations MUST NOT (also) emit a logical encompassing HTTP client span. 2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. From 2bc6a625239118fc55c5d884bbd216c8c6c00f7a Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Mon, 27 Mar 2023 17:58:33 +0200 Subject: [PATCH 3/5] comments --- specification/trace/semantic_conventions/http.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 183db6c30f7..a63fa4e8356 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -123,7 +123,7 @@ This span type represents an outbound HTTP request. There are two ways this can 1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). - In this case, instrumentations MUST NOT (also) emit a logical encompassing HTTP client span. + In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. 2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. @@ -172,7 +172,7 @@ Retries and redirects cause more than one physical HTTP request to be sent. A request is resent when an HTTP client library sends more than one HTTP request to satisfy the same API call. This may happen due to following redirects, authorization challenges, 503 Server Unavailable, network issues, or any other. -Each time an HTTP request is resent, the `http.resend_count` attribute MUST be added to each repeated span and set to the ordinal number of the request resend attempt. +Each time an HTTP request is resent, the `http.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. See the examples for more details about: From a3c61347af4f3614c2525f70110524b750275255 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 7 Apr 2023 10:30:01 -0700 Subject: [PATCH 4/5] Update specification/trace/semantic_conventions/http.md --- specification/trace/semantic_conventions/http.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index a63fa4e8356..dba45b01b57 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -128,7 +128,6 @@ This span type represents an outbound HTTP request. There are two ways this can 2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. In this case, the `http.url` MUST be the originally requested URL, before any HTTP-redirects that may happen when executing the request. - The instrumentation MUST NOT set the `http.resend_count` attribute. For an HTTP client span, `SpanKind` MUST be `Client`. From 14cb3eb952a2cf5938b40bd43a63cacca5f8082c Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 11 Apr 2023 16:47:41 +0200 Subject: [PATCH 5/5] changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4921c3137ad..8525b76ddf1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,9 @@ release. ### Semantic Conventions +- Clarify the scope of the HTTP client span. + ([#3290](https://github.com/open-telemetry/opentelemetry-specification/pull/3290)) + ### Compatibility ### OpenTelemetry Protocol