Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify HTTP client duration #70

Merged
merged 16 commits into from
Jun 9, 2023
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
24 changes: 24 additions & 0 deletions specification/trace/semantic_conventions/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,30 @@ 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.

### 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.
trask marked this conversation as resolved.
Show resolved Hide resolved

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),
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.
trask marked this conversation as resolved.
Show resolved Hide resolved

### HTTP request retries and redirects

Retries and redirects cause more than one physical HTTP request to be sent.
Expand Down