From 4598e9c1105ed348428d8ca9d0fa62a62566379e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 31 May 2023 18:32:35 -0700 Subject: [PATCH 01/13] Clarify HTTP client duration --- CHANGELOG.md | 2 ++ specification/trace/semantic_conventions/http.md | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 298f090d34..089a9fb8ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -68,3 +68,5 @@ release. ([#13](https://github.com/open-telemetry/semantic-conventions/pull/13)) - Clarify `process.runtime.jvm.threads.count` refers to platform threads. ([#54](https://github.com/open-telemetry/semantic-conventions/pull/54)) +- Clarify when HTTP client spans should end. + ([#70](https://github.com/open-telemetry/semantic-conventions/pull/70)) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 155611480a..c309534605 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -153,6 +153,13 @@ This span type represents an outbound HTTP request. There are two ways this can For an HTTP client span, `SpanKind` MUST be `Client`. +HTTP client spans SHOULD end sometime after all the response headers are received. This MAY or MAY NOT include time spent reading the response body. + +HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. + +> **Note** +> It is nice for HTTP client spans to end once the response body has been fully read. However, if there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read). This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| From d5f9d8a153cd44856345e31ff7bd48196f8152cf Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 31 May 2023 19:30:34 -0700 Subject: [PATCH 02/13] Update specification/trace/semantic_conventions/http.md Co-authored-by: James Newton-King --- specification/trace/semantic_conventions/http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index c309534605..f629e8efd9 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -158,7 +158,7 @@ HTTP client spans SHOULD end sometime after all the response headers are receive HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. > **Note** -> It is nice for HTTP client spans to end once the response body has been fully read. However, if there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read). This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. +> It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. An HTTP request ends once the response body has been fully read or the response closes with an error. However, if there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read). This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. | Attribute | Type | Description | Examples | Requirement Level | From c8c906c7a65006d62e5a4fbf1ef2564fc2f373a5 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 31 May 2023 19:53:20 -0700 Subject: [PATCH 03/13] Remove unnecessary (and imprecise) statement --- specification/trace/semantic_conventions/http.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index f629e8efd9..0e52c5885e 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -153,12 +153,10 @@ This span type represents an outbound HTTP request. There are two ways this can For an HTTP client span, `SpanKind` MUST be `Client`. -HTTP client spans SHOULD end sometime after all the response headers are received. This MAY or MAY NOT include time spent reading the response body. - -HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. - > **Note** > It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. An HTTP request ends once the response body has been fully read or the response closes with an error. However, if there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read). This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. +> +> Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. | Attribute | Type | Description | Examples | Requirement Level | From e5ee4cef7b276b323b62acec02df1d80b0620617 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 31 May 2023 20:05:02 -0700 Subject: [PATCH 04/13] or fail to be read --- specification/trace/semantic_conventions/http.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 0e52c5885e..e65a57cdee 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -154,7 +154,12 @@ This span type represents an outbound HTTP request. There are two ways this can For an HTTP client span, `SpanKind` MUST be `Client`. > **Note** -> It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. An HTTP request ends once the response body has been fully read or the response closes with an error. However, if there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read). This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. +> It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. +> An HTTP request ends once the response body has been fully read or the response closes with an error. +> However, if there is any possibility for application code to not fully read the HTTP response +> (and for the HTTP client library to then have to clean up the HTTP response asynchronously), +> the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read, or fail to be read). +> This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. > > Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. From 9cf06e4cb01e47a8c3ef6d3f4be84797aab25d0a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Jun 2023 08:17:48 -0700 Subject: [PATCH 05/13] Normative, new section --- .../trace/semantic_conventions/http.md | 32 +++++++++++++------ 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index e65a57cdee..55f41cc7fd 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -153,16 +153,6 @@ This span type represents an outbound HTTP request. There are two ways this can For an HTTP client span, `SpanKind` MUST be `Client`. -> **Note** -> It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. -> An HTTP request ends once the response body has been fully read or the response closes with an error. -> However, if there is any possibility for application code to not fully read the HTTP response -> (and for the HTTP client library to then have to clean up the HTTP response asynchronously), -> the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read, or fail to be read). -> This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. -> -> Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| @@ -204,6 +194,28 @@ Following attributes MUST be provided **at span creation time** (when provided a Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. +### Ending HTTP client spans + +The HTTP client span SHOULD end when the response body has been fully read or the response closes with an error. + +However, if there is any possibility for application code to not fully read the HTTP response +(and for the HTTP client library to then have to clean up the HTTP response asynchronously), +the HTTP client span MUST be ended earlier (e.g. after the HTTP response headers are read, or fail to be read). + +This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. + +Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. + +> **Note** +> It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. +> An HTTP request ends once the response body has been fully read or the response closes with an error. +> However, if there is any possibility for application code to not fully read the HTTP response +> (and for the HTTP client library to then have to clean up the HTTP response asynchronously), +> the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read, or fail to be read). +> This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. +> +> Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. + ### HTTP request retries and redirects Retries and redirects cause more than one physical HTTP request to be sent. From 2fc3db368126009eeeaf4b8284aa176ceaa93f4e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Jun 2023 08:23:24 -0700 Subject: [PATCH 06/13] Generalize to start and end --- specification/trace/semantic_conventions/http.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 55f41cc7fd..a91ed3af52 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -194,9 +194,11 @@ Following attributes MUST be provided **at span creation time** (when provided a Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. -### Ending HTTP client spans +### HTTP client span duration -The HTTP client span SHOULD end when the response body has been fully read or the response closes with an error. +HTTP client spans SHOULD start sometime before the first request byte is sent. This may or may not include connection time. + +HTTP client spans SHOULD end when the response body has been fully read or the response closes with an error. However, if there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), From b4a5fd76964122a7e8ed0eb9f42540798004a2fa Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Jun 2023 08:32:40 -0700 Subject: [PATCH 07/13] More rewording --- .../trace/semantic_conventions/http.md | 21 ++++++------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index a91ed3af52..861ce5a327 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -198,26 +198,17 @@ Note that in some cases host and port identifiers in the `Host` header might be HTTP client spans SHOULD start sometime before the first request byte is sent. This may or may not include connection time. -HTTP client spans SHOULD end when the response body has been fully read or the response closes with an error. +HTTP client spans SHOULD end be sometime after the HTTP response headers are read (or when they fail to be read). -However, if there is any possibility for application code to not fully read the HTTP response +If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), -the HTTP client span MUST be ended earlier (e.g. after the HTTP response headers are read, or fail to be read). - -This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. +the HTTP client span SHOULD be ended earlier +(e.g. after the HTTP response headers are read, or fail to be read). +This avoids the span being ended asynchronously later on at a time +which is no longer directly associated with the application code which made the HTTP request. Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. -> **Note** -> It is nice for HTTP client spans to represent the complete lifetime of the HTTP request. -> An HTTP request ends once the response body has been fully read or the response closes with an error. -> However, if there is any possibility for application code to not fully read the HTTP response -> (and for the HTTP client library to then have to clean up the HTTP response asynchronously), -> the HTTP client span SHOULD be ended earlier (e.g. after the HTTP response headers are read, or fail to be read). -> This avoids having to end the span asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. -> -> Because of the potential for confusion around this, HTTP client library instrumentations SHOULD document their behavior around ending HTTP client spans. - ### HTTP request retries and redirects Retries and redirects cause more than one physical HTTP request to be sent. From fbea20efeda3dc76ebcea9b88b7669633983de94 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Jun 2023 08:37:49 -0700 Subject: [PATCH 08/13] Better words --- 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 861ce5a327..de1dd5ad6e 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -202,8 +202,8 @@ HTTP client spans SHOULD end be sometime after the HTTP response headers are rea If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), -the HTTP client span SHOULD be ended earlier -(e.g. after the HTTP response headers are read, or fail to be read). +the HTTP client span SHOULD NOT be ended in this cleanup phase +(and instead should end after the HTTP response headers are read, or fail to be read). This avoids the span being ended asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. From c632753832e3bac7d4858acb7f355432498efb74 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Jun 2023 08:55:14 -0700 Subject: [PATCH 09/13] TOC --- 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 de1dd5ad6e..47d0e767b5 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. - [Common Attributes](#common-attributes) * [HTTP request and response headers](#http-request-and-response-headers) - [HTTP client](#http-client) + * [HTTP client span duration](#http-client-span-duration) * [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP server](#http-server) * [HTTP server definitions](#http-server-definitions) @@ -198,12 +199,12 @@ Note that in some cases host and port identifiers in the `Host` header might be HTTP client spans SHOULD start sometime before the first request byte is sent. This may or may not include connection time. -HTTP client spans SHOULD end be sometime after the HTTP response headers are read (or when they fail to be read). +HTTP client spans SHOULD end be sometime after the HTTP response headers are fully read (or when they fail to be read). If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD NOT be ended in this cleanup phase -(and instead should end after the HTTP response headers are read, or fail to be read). +(and instead should end after the HTTP response headers are fully read, or fail to be read). This avoids the span being ended asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. From 0fbac166ab0ea52cede07686fc174b2f61e2cc02 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 1 Jun 2023 11:18:22 -0700 Subject: [PATCH 10/13] Refinement --- 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 47d0e767b5..41edb86b96 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -197,9 +197,10 @@ Note that in some cases host and port identifiers in the `Host` header might be ### HTTP client span duration -HTTP client spans SHOULD start sometime before the first request byte is sent. This may or may not include connection time. +There are some minimal constraints that SHOULD be honored: -HTTP client spans SHOULD end be sometime after the HTTP response headers are fully read (or when they fail to be read). +* HTTP client spans SHOULD start sometime before the first request byte is sent. This may or may not include connection time. +* HTTP client spans SHOULD end be sometime after the HTTP response headers are fully read (or when they fail to be read). This may or may not include reading the response body. If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), From 604d1b2242d98484363879d3fcc50d42bdc86180 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 5 Jun 2023 14:06:51 -0700 Subject: [PATCH 11/13] Less specific --- 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 41edb86b96..b2b8351235 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -204,8 +204,8 @@ There are some minimal constraints that SHOULD be honored: If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), -the HTTP client span SHOULD NOT be ended in this cleanup phase -(and instead should end after the HTTP response headers are fully read, or fail to be read). +the HTTP client span SHOULD NOT be ended in this cleanup phase, +and instead SHOULD end at some point after the HTTP response headers are fully read, or fail to be read. This avoids the span being ended asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. From 9cb57bfbba773cd334bc9fd7ae8cb9f03e5b587b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 5 Jun 2023 14:07:25 -0700 Subject: [PATCH 12/13] Clarity --- specification/trace/semantic_conventions/http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index b2b8351235..58fec100ba 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -205,7 +205,7 @@ There are some minimal constraints that SHOULD be honored: If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously), the HTTP client span SHOULD NOT be ended in this cleanup phase, -and instead SHOULD end at some point after the HTTP response headers are fully read, or fail to be read. +and instead SHOULD end at some point after the HTTP response headers are fully read (or fail to be read). This avoids the span being ended asynchronously later on at a time which is no longer directly associated with the application code which made the HTTP request. From d285cb7c2f25d23682ff0f0562a3835c4ef7d94d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 5 Jun 2023 14:58:35 -0700 Subject: [PATCH 13/13] Update specification/trace/semantic_conventions/http.md Co-authored-by: Reiley Yang --- specification/trace/semantic_conventions/http.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 58fec100ba..0e3187d6ca 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -200,7 +200,7 @@ Note that in some cases host and port identifiers in the `Host` header might be There are some minimal constraints that SHOULD be honored: * HTTP client spans SHOULD start sometime before the first request byte is sent. This may or may not include connection time. -* HTTP client spans SHOULD end be sometime after the HTTP response headers are fully read (or when they fail to be read). This may or may not include reading the response body. +* HTTP client spans SHOULD end sometime after the HTTP response headers are fully read (or when they fail to be read). This may or may not include reading the response body. If there is any possibility for application code to not fully read the HTTP response (and for the HTTP client library to then have to clean up the HTTP response asynchronously),