{"id":908,"library":"opentelemetry-instrumentation-httpx","title":"OpenTelemetry HTTPX Instrumentation","description":"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.","status":"active","version":"0.61b0","language":"python","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","tracing","http client","httpx","asynchronous","instrumentation"],"install":[{"cmd":"pip install opentelemetry-instrumentation-httpx opentelemetry-sdk opentelemetry-exporter-otlp-proto-http httpx","lang":"bash","label":"Full Installation"}],"dependencies":[{"reason":"The HTTP client being instrumented.","package":"httpx"},{"reason":"Core OpenTelemetry API.","package":"opentelemetry-api"},{"reason":"Core OpenTelemetry SDK for tracer providers and span processors.","package":"opentelemetry-sdk"},{"reason":"Common exporter for sending telemetry data to an OpenTelemetry Collector via HTTP, often used in examples.","package":"opentelemetry-exporter-otlp-proto-http","optional":true}],"imports":[{"note":"The main class to instrument HTTPX clients.","symbol":"HTTPXClientInstrumentor","correct":"from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor"},{"note":"Alternative for explicit synchronous transport instrumentation.","symbol":"SyncOpenTelemetryTransport","correct":"from opentelemetry.instrumentation.httpx import SyncOpenTelemetryTransport"},{"note":"Alternative for explicit asynchronous transport instrumentation.","symbol":"AsyncOpenTelemetryTransport","correct":"from opentelemetry.instrumentation.httpx import AsyncOpenTelemetryTransport"}],"quickstart":{"code":"import asyncio\nimport httpx\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor\nfrom opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor\nimport os\n\n# Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": os.environ.get(\"OTEL_SERVICE_NAME\", \"httpx-client-app\")})\nprovider = TracerProvider(resource=resource)\nprocessor = BatchSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# Instrument all HTTPX clients\nHTTPXClientInstrumentor().instrument()\n\nasync def make_async_request():\n    print(\"\\nMaking async HTTPX request...\")\n    async with httpx.AsyncClient() as client:\n        response = await client.get(\"https://example.com\")\n        print(f\"Async request status: {response.status_code}\")\n\ndef make_sync_request():\n    print(\"\\nMaking sync HTTPX request...\")\n    with httpx.Client() as client:\n        response = client.get(\"https://example.com\")\n        print(f\"Sync request status: {response.status_code}\")\n\nif __name__ == \"__main__\":\n    make_sync_request()\n    asyncio.run(make_async_request())\n    print(\"\\nTraces should be printed above (if ConsoleSpanExporter is used).\")\n","lang":"python","description":"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)."},"warnings":[{"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.","message":"OpenTelemetry'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`).","severity":"breaking","affected_versions":"<=0.60b0"},{"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)`.","message":"HTTPX 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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Pre-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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"By default, sensitive HTTP headers and request/response bodies are not captured or are sanitized. Directly logging or capturing raw payloads can expose sensitive data.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Networking 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':35 'align':43 'api':23 'asynchron':22,59 'automat':8 'beta':40 'cadenc':52 'client':15,57 'contrib':31 'core':46 'develop':36 'frequent':39 'general':42 'http':14,56 'httpx':2,5,11,58 'instrument':3,6,60 'modern':13 'observ':54 'opentelemetri':1,4,29,47,53 'part':26 'project':32 'provid':7 'python':17,30,48 'receiv':38 'releas':41,51 'sdk':49 'support':18 'synchron':20 'trace':9,55","created_at":"2026-03-29T06:07:13.244123+00:00","updated_at":"2026-04-16T17:41:45.882788+00:00","problems":{"verify_error":"error: Failed to parse: `opentelemetry-instrumentation-httpx opentelemetry-sdk opentelemetry-exporter-otlp-proto-http httpx`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `o`\nopentelemetry-instrumentation-httpx opentelemetry-sdk opentelemetry-exporter-otlp-proto-http htt"},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.65b0","cli_name":"","cli_version":null,"type":"library","homepage":"https://opentelemetry.io","github":"https://github.com/open-telemetry/opentelemetry-python-contrib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opentelemetry-instrumentation-httpx/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","http-networking","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":"verified"}}