diff --git a/CHANGELOG.md b/CHANGELOG.md index adc810022af..c30837af071 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,6 +48,8 @@ release. ([#1810](https://github.com/open-telemetry/opentelemetry-specification/pull/1810)) - Clarifications for `http.client_ip` and `http.host`. ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890)) +- Add HTTP request and response headers semantic conventions. + ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898)) ### Compatibility diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index ad2f50d33f1..82f7696f78a 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -14,6 +14,7 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Name](#name) - [Status](#status) - [Common Attributes](#common-attributes) + - [HTTP request and response headers](#http-request-and-response-headers) - [HTTP client](#http-client) - [HTTP server](#http-server) - [HTTP server definitions](#http-server-definitions) @@ -87,6 +88,21 @@ Don't set the span status description if the reason can be inferred from `http.s It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +### HTTP request and response headers + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | No | +| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | No | + +**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. +Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. + +Some HTTP headers - `Host` and `User-Agent` - are already captured in the `http.host` and `http.user_agent` attributes. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. + +**[2]:** The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + [network attributes]: span-general.md#general-network-connection-attributes ## HTTP client