Skip to content

Commit

Permalink
HTTP client span clarification (#3290)
Browse files Browse the repository at this point in the history
Related to
https://github.com/open-telemetry/opentelemetry-specification/issues/3155
and
#3234

## Changes

This PR contains the less controversial parts of
#3234;
it describes how the `http.resend_count` attribute should be used, and
proposes two ways of instrumenting HTTP clients.
  • Loading branch information
Mateusz Rzeszutek authored Apr 14, 2023
1 parent ae82b77 commit f922f5f
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 9 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ release.

### Semantic Conventions

- Clarify the scope of the HTTP client span.
([#3290](https://github.com/open-telemetry/opentelemetry-specification/pull/3290))
- Add moratorium on relying on schema transformations for telemetry stability
([#3380](https://github.com/open-telemetry/opentelemetry-specification/pull/3380))

Expand Down
24 changes: 15 additions & 9 deletions specification/trace/semantic_conventions/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,12 +119,17 @@ 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).
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.
In this case, the `http.url` MUST be the originally requested URL, before any HTTP-redirects that may happen when executing the request.

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`.

<!-- semconv trace.http.client(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand Down Expand Up @@ -165,13 +170,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 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:

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

Expand Down

0 comments on commit f922f5f

Please sign in to comment.