Registry / observability / opentelemetry-instrumentation-httpx

opentelemetry-instrumentation-httpx

library0.65b0pypypi✓ verified 24d ago

OpenTelemetry HTTPX Instrumentation provides automatic tracing for HTTPX, a modern HTTP client for Python supporting both synchronous and asynchronous APIs. It is part of the OpenTelemetry Python Contrib project, which is actively developed and receives frequent beta releases, generally aligning with the core OpenTelemetry Python SDK's release cadence.

observability http-networking aws

pip install opentelemetry-instrumentation-httpx opentelemetry-sdk opentelemetry-exporter-otlp-proto-http httpx

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENTELEMETRY-INST

opentelemetry-instrumentation-httpx

observabilitypythonv0.65b0

Install

4.5s avg

Import

508ms

Disk

34MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.65b0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.532s · 34.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.5s · import 0.484s · 35MB

34MB installed

● package 34MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HTTPXClientInstrumentor

✓ from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

The main class to instrument HTTPX clients.

SyncOpenTelemetryTransport

✓ from opentelemetry.instrumentation.httpx import SyncOpenTelemetryTransport

Alternative for explicit synchronous transport instrumentation.

AsyncOpenTelemetryTransport

✓ from opentelemetry.instrumentation.httpx import AsyncOpenTelemetryTransport

Alternative for explicit asynchronous transport instrumentation.

This quickstart demonstrates how to set up the OpenTelemetry SDK and instrument both synchronous and asynchronous HTTPX clients. After running, you should see trace information printed to the console (if using ConsoleSpanExporter).

import asyncio import httpx from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor import os # Configure OpenTelemetry SDK resource = Resource.create({"service.name": os.environ.get("OTEL_SERVICE_NAME", "httpx-client-app")}) provider = TracerProvider(resource=resource) processor = BatchSpanProcessor(ConsoleSpanExporter()) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # Instrument all HTTPX clients HTTPXClientInstrumentor().instrument() async def make_async_request(): print("\nMaking async HTTPX request...") async with httpx.AsyncClient() as client: response = await client.get("https://example.com") print(f"Async request status: {response.status_code}") def make_sync_request(): print("\nMaking sync HTTPX request...") with httpx.Client() as client: response = client.get("https://example.com") print(f"Sync request status: {response.status_code}") if __name__ == "__main__": make_sync_request() asyncio.run(make_async_request()) print("\nTraces should be printed above (if ConsoleSpanExporter is used).")

Debug

Known issues

breakingOpenTelemetry's HTTP Semantic Conventions have been stabilized, leading to attribute name changes (e.g., `http.url` to `url.full`, `http.status_code` to `http.response.status_code`).

fix

Update to the latest instrumentation version. To facilitate migration, set the environment variable `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup` to emit both old and new attributes during transition, then switch to `http` to emit only stable attributes.

affects: <=0.60b0

gotchaHTTPX clients or their subclasses instantiated *before* `HTTPXClientInstrumentor().instrument()` is called will not be instrumented. This is particularly relevant when using libraries that internally create HTTPX clients (e.g., `openai-python`).

fix

Ensure `HTTPXClientInstrumentor().instrument()` is called as early as possible in your application's lifecycle, preferably before any HTTPX clients are created. For single-client instrumentation, use `HTTPXClientInstrumentor.instrument_client(client_instance)`.

affects: All versions

gotchaPre-fork servers (like Gunicorn with multiple workers) can cause issues with metrics generation when using OpenTelemetry auto-instrumentation due to threading and lock inconsistencies in child processes.

fix

Consider using a single worker for pre-fork servers or exploring workarounds like programmatic auto-instrumentation or specific configurations for your deployment environment. Refer to OpenTelemetry troubleshooting guides for detailed strategies.

affects: All versions

gotchaBy default, sensitive HTTP headers and request/response bodies are not captured or are sanitized. Directly logging or capturing raw payloads can expose sensitive data.

fix

Use the environment variable `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` with a comma-delimited list of header names (regex supported) to redact values. For custom payload logging, implement `request_hook` and `response_hook` functions, being mindful of data sensitivity.

affects: All versions

gotchaNetworking requests via HTTPX may fail with `SSL: CERTIFICATE_VERIFY_FAILED` errors, particularly in minimal container environments (e.g., `python:*-slim` Docker images). This indicates a missing or outdated root CA certificate bundle required to verify SSL connections.

fix

Ensure your environment has the necessary root CA certificates installed. For Debian-based Docker images, this typically means adding `RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*` to your Dockerfile. For other environments, ensure your system's SSL certificate store is up-to-date and correctly configured.

affects: All versions

gotchaWhen running in minimal environments (e.g., Alpine Docker images), SSL certificate validation for HTTPS requests may fail with `CERTIFICATE_VERIFY_FAILED`. This is an environmental issue due to missing root CA certificates, not a bug in the instrumentation, but it prevents HTTPX requests from completing.

fix

Ensure your environment has the necessary CA certificates installed (e.g., `apk add ca-certificates` on Alpine Linux, or mount appropriate certificate bundles). For testing, you can disable SSL verification in HTTPX by passing `verify=False` to the `httpx.Client` constructor, but this is not recommended for production environments.

affects: All versions

Upgrade

Version history

0.65b0latest on PyPI · released Jul 16, 2026

Audit

Dependencies

httpxrequiredThe HTTP client being instrumented.

opentelemetry-apirequiredCore OpenTelemetry API.

opentelemetry-sdkrequiredCore OpenTelemetry SDK for tracer providers and span processors.

opentelemetry-exporter-otlp-proto-httpoptionalCommon exporter for sending telemetry data to an OpenTelemetry Collector via HTTP, often used in examples.

Agent activity

25 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/open-telemetry/opentelemetry-python-contrib ↗

packagehttps://pypi.org/project/opentelemetry-instrumentation-httpx/ ↗

homepagehttps://opentelemetry.io ↗