From 452130044e614f45441fc9a276f396d0533b0de8 Mon Sep 17 00:00:00 2001 From: Harshal Parekh Date: Fri, 8 May 2026 05:07:29 -0500 Subject: [PATCH 1/4] Document FastAPI instrumentation setup Clarify FastAPI auto-instrumentation configuration, propagation, WebSocket behavior, and log export. Also surface the opentelemetry-instrumentation README in the generated docs menu. Assisted-by: OpenAI Codex --- docs/instrumentation/base/instrumentation.rst | 6 +- .../instrumentation/fastapi/__init__.py | 55 +++++++++++++++++++ 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/instrumentation/base/instrumentation.rst b/docs/instrumentation/base/instrumentation.rst index 9c01b6b6f4..bdc8b6b678 100644 --- a/docs/instrumentation/base/instrumentation.rst +++ b/docs/instrumentation/base/instrumentation.rst @@ -1,5 +1,7 @@ -OpenTelemetry Python Instrumentor -================================= +.. include:: ../../../opentelemetry-instrumentation/README.rst + +API +--- .. automodule:: opentelemetry.instrumentation :members: diff --git a/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py b/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py index 11d64914e2..8c296e9d82 100644 --- a/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py @@ -18,6 +18,61 @@ async def foobar(): FastAPIInstrumentor.instrument_app(app) +Auto-instrumentation +******************** + +FastAPI can also be instrumented without code changes by using the +``opentelemetry-instrument`` command from the +`opentelemetry-instrumentation `_ +package together with the +`opentelemetry-distro `_ +package: + +.. code-block:: sh + + pip install "opentelemetry-distro[otlp]" opentelemetry-instrumentation-fastapi + opentelemetry-instrument uvicorn app:app + +When auto-instrumentation is used with ``opentelemetry-distro``, the SDK +configuration is read from standard OpenTelemetry environment variables such as +``OTEL_SERVICE_NAME``, ``OTEL_TRACES_EXPORTER``, ``OTEL_METRICS_EXPORTER``, +``OTEL_LOGS_EXPORTER``, ``OTEL_EXPORTER_OTLP_ENDPOINT``, and +``OTEL_EXPORTER_OTLP_PROTOCOL``. FastAPI-specific options, such as excluded +URLs and HTTP header capture, are documented below. When using +``FastAPIInstrumentor.instrument_app(app)`` directly, configure the +OpenTelemetry SDK providers and exporters in application code or use a distro +package to configure them. + +Trace propagation +***************** + +Incoming context is extracted automatically from FastAPI request headers by the +underlying ASGI instrumentation, using the configured global OpenTelemetry +propagator. No manual intervention is needed for incoming HTTP requests. +Outgoing context propagation is handled by the instrumentation for the client +library making the outbound request, such as HTTPX, Requests, or aiohttp. + +WebSocket connections are instrumented as ASGI ``websocket`` scopes. Context is +extracted from the WebSocket handshake headers, and spans are created for the +connection and ASGI send/receive events. Propagation data inside WebSocket +message payloads is not parsed automatically. + +Logs +**** + +FastAPI instrumentation emits traces and metrics. To export Python ``logging`` +records as OpenTelemetry logs, install and enable the +`opentelemetry-instrumentation-logging `_ +package. With auto-instrumentation and ``opentelemetry-distro``, set +``OTEL_LOGS_EXPORTER`` (for example, ``otlp``) to configure log export. Set +``OTEL_PYTHON_LOG_CORRELATION=true`` when log messages should include the +current trace and span IDs in the formatted log output. + +OpenTelemetry logs are exported as log records that can be correlated with +traces. They are not added to spans as span events automatically; use +``span.add_event(...)`` for application data that should be recorded as span +events. + Configuration ------------- From 3b7a2e6a32eaa7c0c95f858cf28a741ae916e4b5 Mon Sep 17 00:00:00 2001 From: Harshal Parekh Date: Sun, 10 May 2026 02:01:47 -0500 Subject: [PATCH 2/4] add changelog --- CHANGELOG.md | 4 ++ .../instrumentation/fastapi/__init__.py | 56 ++++++------------- 2 files changed, 21 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f606c7c6a5..60074e648b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add `BaggageLogProcessor` to `opentelemetry-processor-baggage` ([#4371](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4371)) +- `opentelemetry-instrumentation-fastapi`: Clarify documentation for zero-code setup, propagation, and logs + ([#4555](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4555)) +- `opentelemetry-instrumentation`: Include the package README in the generated documentation + ([#4555](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4555)) - `opentelemetry-instrumentation-system-metrics`: Add support for `process.disk.io` metric in system-metrics instrumentation ([#4397](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/4397)) - Switch to SPDX license headers and add CI enforcement diff --git a/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py b/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py index 8c296e9d82..ad26fbc76a 100644 --- a/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py @@ -24,53 +24,31 @@ async def foobar(): FastAPI can also be instrumented without code changes by using the ``opentelemetry-instrument`` command from the `opentelemetry-instrumentation `_ -package together with the -`opentelemetry-distro `_ -package: - -.. code-block:: sh - - pip install "opentelemetry-distro[otlp]" opentelemetry-instrumentation-fastapi - opentelemetry-instrument uvicorn app:app - -When auto-instrumentation is used with ``opentelemetry-distro``, the SDK -configuration is read from standard OpenTelemetry environment variables such as -``OTEL_SERVICE_NAME``, ``OTEL_TRACES_EXPORTER``, ``OTEL_METRICS_EXPORTER``, -``OTEL_LOGS_EXPORTER``, ``OTEL_EXPORTER_OTLP_ENDPOINT``, and -``OTEL_EXPORTER_OTLP_PROTOCOL``. FastAPI-specific options, such as excluded -URLs and HTTP header capture, are documented below. When using -``FastAPIInstrumentor.instrument_app(app)`` directly, configure the -OpenTelemetry SDK providers and exporters in application code or use a distro -package to configure them. +package. For installation, runtime command, exporter configuration, and +environment variables, see +`Python zero-code instrumentation `_. +Install ``opentelemetry-instrumentation-fastapi`` in the same environment so +the FastAPI integration is available to auto-instrumentation. FastAPI-specific +options, such as excluded URLs and HTTP header capture, are documented below. Trace propagation ***************** -Incoming context is extracted automatically from FastAPI request headers by the -underlying ASGI instrumentation, using the configured global OpenTelemetry -propagator. No manual intervention is needed for incoming HTTP requests. -Outgoing context propagation is handled by the instrumentation for the client -library making the outbound request, such as HTTPX, Requests, or aiohttp. - -WebSocket connections are instrumented as ASGI ``websocket`` scopes. Context is -extracted from the WebSocket handshake headers, and spans are created for the -connection and ASGI send/receive events. Propagation data inside WebSocket -message payloads is not parsed automatically. +FastAPI instrumentation uses the underlying ASGI instrumentation, which extracts +incoming context from request headers using the configured global OpenTelemetry +propagator. WebSocket connections are instrumented as ASGI ``websocket`` scopes, +with context extracted from the handshake headers. Propagation data inside +WebSocket message payloads is not parsed automatically. For more information, +see `Python context propagation `_ +and `Python distro configuration `_. Logs **** -FastAPI instrumentation emits traces and metrics. To export Python ``logging`` -records as OpenTelemetry logs, install and enable the -`opentelemetry-instrumentation-logging `_ -package. With auto-instrumentation and ``opentelemetry-distro``, set -``OTEL_LOGS_EXPORTER`` (for example, ``otlp``) to configure log export. Set -``OTEL_PYTHON_LOG_CORRELATION=true`` when log messages should include the -current trace and span IDs in the formatted log output. - -OpenTelemetry logs are exported as log records that can be correlated with -traces. They are not added to spans as span events automatically; use -``span.add_event(...)`` for application data that should be recorded as span +FastAPI instrumentation does not convert Python ``logging`` records to span +events. For zero-code log export, see +`Python logs auto-instrumentation `_. +Use ``span.add_event(...)`` for application data that should be recorded as span events. Configuration From c2ca6a65a0fa0952a295f5408e7768d78bfc5c65 Mon Sep 17 00:00:00 2001 From: Harshal Parekh Date: Wed, 13 May 2026 16:20:28 -0500 Subject: [PATCH 3/4] Use towncrier fragment for FastAPI docs Assisted-by: OpenAI Codex --- .changelog/4555.added | 1 + CHANGELOG.md | 4 ---- 2 files changed, 1 insertion(+), 4 deletions(-) create mode 100644 .changelog/4555.added diff --git a/.changelog/4555.added b/.changelog/4555.added new file mode 100644 index 0000000000..daafeca51a --- /dev/null +++ b/.changelog/4555.added @@ -0,0 +1 @@ +`opentelemetry-instrumentation-fastapi`, `opentelemetry-instrumentation`: update docs diff --git a/CHANGELOG.md b/CHANGELOG.md index cecc69992f..dd24fb0ca5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,10 +13,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- `opentelemetry-instrumentation-fastapi`: Clarify documentation for zero-code setup, propagation, and logs - ([#4555](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4555)) -- `opentelemetry-instrumentation`: Include the package README in the generated documentation - ([#4555](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4555)) - Add `BaggageLogProcessor` to `opentelemetry-processor-baggage` ([#4371](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4371)) - `opentelemetry-instrumentation-system-metrics`: Add support for `process.disk.io` metric in system-metrics instrumentation From 37884a646fc2e815eebf7f30999d4de1d4208734 Mon Sep 17 00:00:00 2001 From: Harshal Parekh Date: Fri, 15 May 2026 17:21:12 -0500 Subject: [PATCH 4/4] Update docs/instrumentation/base/instrumentation.rst Co-authored-by: Tammy Baylis <96076570+tammy-baylis-swi@users.noreply.github.com> --- docs/instrumentation/base/instrumentation.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/instrumentation/base/instrumentation.rst b/docs/instrumentation/base/instrumentation.rst index bdc8b6b678..c3ee9da976 100644 --- a/docs/instrumentation/base/instrumentation.rst +++ b/docs/instrumentation/base/instrumentation.rst @@ -1,4 +1,5 @@ .. include:: ../../../opentelemetry-instrumentation/README.rst + :end-before: References API ---