OpenTelemetry HTTPX Instrumentation

Warnings

• breaking 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`).
  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.
• gotcha 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`).
  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)`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-httpx opentelemetry-sdk opentelemetry-exporter-otlp-proto-http httpx Full Installation

Imports

• 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.

Quickstart

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).")