From 6077d98b6284e14b182b5ad9768196423ef75cc8 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Wed, 31 Dec 2025 12:19:04 +0100 Subject: [PATCH 1/3] docs: document http headers capturing and sanitization --- docs/reference/edot-python/configuration.md | 84 +++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/docs/reference/edot-python/configuration.md b/docs/reference/edot-python/configuration.md index e9f16b68..2ed0f996 100644 --- a/docs/reference/edot-python/configuration.md +++ b/docs/reference/edot-python/configuration.md @@ -129,6 +129,90 @@ Instrument Python `logging` module to format and forward logs in OTLP format is export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true ``` +#### HTTP headers capture + +You can capture HTTP headers as span attributes on both client and server HTTP instrumentations according to [HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http-spans/), refer to [`http.request.header.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-request-header) and [`http.response.header.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-response-header) attributes. + +##### server + +```{applies_to} +product: + edot_python: preview 1.11.0 +``` + +To define which HTTP headers you want to capture, provide a comma-separated list +of HTTP header names via the environment variables +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST` and +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`, e.g.: + +```sh +export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="Accept-Encoding,User-Agent,Referer" +export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="Last-Modified,Content-Type" +``` + +These configuration options are supported by the following HTTP server instrumentations: + +- Aiohttp-server +- ASGI +- Django +- Falcon +- FastAPI +- Flask +- Pyramid +- Starlette +- Tornado +- WSGI + +##### client + +```{applies_to} +product: + edot_python: preview 1.12.0 +``` + +To define which HTTP headers you want to capture, provide a comma-separated list +of HTTP header names via the environment variables +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST` and +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE`, e.g.: + +```sh +export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST="Accept-Encoding,User-Agent,Referer" +export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE="Last-Modified,Content-Type" +``` + +These configuration options are supported by the following HTTP client instrumentations: + +- Aiohttp-client +- httpx +- requests +- urllib +- urllib3 + +##### Sanitization of captured headers + +```{applies_to} +product: + edot_python: preview 1.11.0 +``` + +Some headers may contain sensitive data such as PII (Personally Identifiable information), +session keys, passwords, etc. To avoid storing this data OpenTelemetry Python +provides a sanitization system via the `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` +environment variable. +Set the environment variable +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` to a comma delimited +list of HTTP header names to be sanitized. Regexes may be used, and all header +names will be matched in a case-insensitive manner. + +For example, + +```sh +export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS=".*session.*,set-cookie" +``` + +will replace the value of headers such as `session-id` and `set-cookie` with +`[REDACTED]` in the span. + #### Differences from OpenTelemetry Python EDOT Python uses different defaults than OpenTelemetry Python for the following configuration options: From e0478eb7c33c173f411dd1f210212728618006d8 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Wed, 7 Jan 2026 10:45:01 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Fabrizio Ferri-Benedetti --- docs/reference/edot-python/configuration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/edot-python/configuration.md b/docs/reference/edot-python/configuration.md index 2ed0f996..0c0362d3 100644 --- a/docs/reference/edot-python/configuration.md +++ b/docs/reference/edot-python/configuration.md @@ -131,7 +131,7 @@ export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true #### HTTP headers capture -You can capture HTTP headers as span attributes on both client and server HTTP instrumentations according to [HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http-spans/), refer to [`http.request.header.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-request-header) and [`http.response.header.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-response-header) attributes. +You can capture HTTP headers as span attributes on both client and server HTTP instrumentations according to [HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http-spans/). Refer to [`http.request.header.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-request-header) and [`http.response.header.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/#http-response-header) attributes. ##### server @@ -141,9 +141,9 @@ product: ``` To define which HTTP headers you want to capture, provide a comma-separated list -of HTTP header names via the environment variables +of HTTP header names through the environment variables `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST` and -`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`, e.g.: +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`, for example: ```sh export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="Accept-Encoding,User-Agent,Referer" @@ -171,9 +171,9 @@ product: ``` To define which HTTP headers you want to capture, provide a comma-separated list -of HTTP header names via the environment variables +of HTTP header names through the environment variables `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST` and -`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE`, e.g.: +`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE`, for example: ```sh export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST="Accept-Encoding,User-Agent,Referer" From 5de41390498ef8c996e79a375a2f22cbb6aafe6a Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Wed, 7 Jan 2026 15:58:32 +0100 Subject: [PATCH 3/3] Update docs/reference/edot-python/configuration.md Co-authored-by: Fabrizio Ferri-Benedetti --- docs/reference/edot-python/configuration.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/reference/edot-python/configuration.md b/docs/reference/edot-python/configuration.md index 0c0362d3..cd25bb85 100644 --- a/docs/reference/edot-python/configuration.md +++ b/docs/reference/edot-python/configuration.md @@ -195,24 +195,16 @@ product: edot_python: preview 1.11.0 ``` -Some headers may contain sensitive data such as PII (Personally Identifiable information), -session keys, passwords, etc. To avoid storing this data OpenTelemetry Python -provides a sanitization system via the `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` +Some headers might contain sensitive data such as personally identifiable information (PII), session keys, passwords, and so on. To avoid storing this data, OpenTelemetry Python provides a sanitization system through the `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` environment variable. -Set the environment variable -`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` to a comma delimited -list of HTTP header names to be sanitized. Regexes may be used, and all header -names will be matched in a case-insensitive manner. +Set the environment variable to a comma delimited list of HTTP header names to be sanitized. You can use use regular expressions. +All header names are matched in a case-insensitive manner. -For example, +This example replaces the values of the `set-cookie` header and headers such as `session-id` that matches the provided regular expression with `[REDACTED]` in the span: ```sh export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS=".*session.*,set-cookie" ``` - -will replace the value of headers such as `session-id` and `set-cookie` with -`[REDACTED]` in the span. - #### Differences from OpenTelemetry Python EDOT Python uses different defaults than OpenTelemetry Python for the following configuration options: