diff --git a/CHANGELOG.md b/CHANGELOG.md index 9045fa701a0..02775145def 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -236,6 +236,8 @@ release. ([#1916](https://github.com/open-telemetry/opentelemetry-specification/pull/1916)) - Change meaning and discourage use of `faas.trigger` for FaaS clients (outgoing). ([#1921](https://github.com/open-telemetry/opentelemetry-specification/pull/1921)) +- Define span structure for HTTP retries and redirects. + ([#2078](https://github.com/open-telemetry/opentelemetry-specification/pull/2078)) - Clarify difference between container.name and k8s.container.name ([#1980](https://github.com/open-telemetry/opentelemetry-specification/pull/1980)) diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 20adebca11c..85b9febb9f4 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -104,6 +104,13 @@ groups: brief: > The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. examples: 5493 + - id: retry_count + type: int + brief: > + The ordinal number of request re-sending attempt. + required: + conditional: If and only if a request was retried. + examples: 3 - ref: net.peer.name sampling_relevant: true - ref: net.peer.ip diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 4e5c0e9d771..16806a1a45e 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -14,11 +14,14 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Status](#status) - [Common Attributes](#common-attributes) * [HTTP request and response headers](#http-request-and-response-headers) + * [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP client](#http-client) - [HTTP server](#http-server) * [HTTP server definitions](#http-server-definitions) * [HTTP Server semantic conventions](#http-server-semantic-conventions) - [HTTP client-server example](#http-client-server-example) +- [HTTP retries examples](#http-retries-examples) +- [HTTP redirects examples](#http-redirects-examples) @@ -70,6 +73,7 @@ Don't set the span status description if the reason can be inferred from `http.s | `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | No | | `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No | | `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No | +| `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | If and only if a request was retried. | | [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No | | [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | No | | [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | No | @@ -121,6 +125,17 @@ Users MAY explicitly configure instrumentations to capture them even though it i [network attributes]: span-general.md#general-network-connection-attributes +### HTTP request retries and redirects + +Retries and redirects cause more than one physical HTTP request to be sent. +A CLIENT span SHOULD be created for each one of these physical requests. +No span is created corresponding to the "logical" (encompassing) request. + +For retries, `http.retry_count` attribute SHOULD be added to each retry span +with the value that reflects the ordinal number of request retry attempt. + +See [examples](#http-retries-examples) for more details. + ## HTTP client This span type represents an outbound HTTP request. @@ -280,3 +295,67 @@ If set, it would be but due to `http.scheme`, `http.host` and `http.target` being set, it would be redundant. As explained above, these separate values are preferred but if for some reason the URL is available but the other values are not, URL can replace `http.scheme`, `http.host` and `http.target`. + +## HTTP retries examples + +Example of retries in the presence of a trace started by an inbound request: + +``` +request (SERVER, trace=t1, span=s1) + | + -- GET / - 500 (CLIENT, trace=t1, span=s2) + | | + | --- server (SERVER, trace=t1, span=s3) + | + -- GET / - 500 (CLIENT, trace=t1, span=s4, http.retry_count=1) + | | + | --- server (SERVER, trace=t1, span=s5) + | + -- GET / - 200 (CLIENT, trace=t1, span=s6, http.retry_count=2) + | + --- server (SERVER, trace=t1, span=s7) +``` + +Example of retries with no trace started upfront: + +``` +GET / - 500 (CLIENT, trace=t1, span=s1) + | + --- server (SERVER, trace=t1, span=s2) + +GET / - 500 (CLIENT, trace=t2, span=s1, http.retry_count=1) + | + --- server (SERVER, trace=t2, span=s2) + +GET / - 200 (CLIENT, trace=t3, span=s1, http.retry_count=2) + | + --- server (SERVER, trace=t3, span=s1) +``` + +## HTTP redirects examples + +Example of redirects in the presence of a trace started by an inbound request: + +``` +request (SERVER, trace=t1, span=s1) + | + -- GET / - 302 (CLIENT, trace=t1, span=s2) + | | + | --- server (SERVER, trace=t1, span=s3) + | + -- GET /hello - 200 (CLIENT, trace=t1, span=s4 ]) + | + --- server (SERVER, trace=t1, span=s5) +``` + +Example of redirects with no trace started upfront: + +``` +GET / - 302 (CLIENT, trace=t1, span=s1) + | + --- server (SERVER, trace=t1, span=s2) + +GET /hello - 200 (CLIENT, trace=t2, span=s1 ]) + | + --- server (SERVER, trace=t2, span=s2) +```