From dcc10ee673621274c866a35e96f45e4e3eeea249 Mon Sep 17 00:00:00 2001 From: ChengJinbao Date: Wed, 9 Mar 2022 02:22:45 +0100 Subject: [PATCH] Define span structure for HTTP retries and redirects (#2078) This PR clarifies semantic conventions for HTTP retries and redirects and defines a span structure and linking as well as span attributes for retries. Changes were discussed recently at Instrumentation SIG meetings. This change addresses a scenario which is in the scope for bringing the existing HTTP semantic conventions for tracing to an initial stable state, see related [otep #174](https://github.com/open-telemetry/oteps/pull/174). --- CHANGELOG.md | 2 + semantic_conventions/trace/http.yaml | 7 ++ .../trace/semantic_conventions/http.md | 79 +++++++++++++++++++ 3 files changed, 88 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9045fa7..0277514 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 20adebc..85b9feb 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 4e5c0e9..16806a1 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) +```