OpenTelemetry Instrumentation for Requests

opentelemetry-instrumentation-requests automatically wraps the popular requests HTTP client library so every outbound HTTP call creates an OpenTelemetry span, with no changes needed at each call site. It captures HTTP method, URL, status code, and (optionally) request/response headers as span attributes following OpenTelemetry’s HTTP semantic conventions.

The instrumentation supports request/response hooks for adding custom span attributes, configurable header capture via environment variables, IP address recording, and User-Agent synthetic-request filtering — making it a drop-in way to get distributed tracing across services that call out over HTTP via requests.

What You Get

• A RequestsInstrumentor that patches requests.Session globally with one .instrument() call
• Automatic HTTP client spans with method, URL, and status code attributes
• Request/response hooks for adding custom span attributes per call
• Configurable capture of specific request/response headers via environment variables
• Support for excluding URLs from tracing and recording client IP addresses

Common Use Cases

• Adding distributed tracing to any service that calls external APIs via requests
• Correlating outbound HTTP calls with the rest of a request’s trace in a microservices architecture
• Auditing and debugging slow or failing third-party API calls with span-level timing
• Capturing custom request/response metadata (headers, hooks) for domain-specific observability needs

Under The Hood

Architecture — the instrumentor subclasses BaseInstrumentor and, on _instrument(), wraps requests.Session.send (the single choke point every requests API funnels through) with a traced version that starts a client span, injects trace context into outgoing headers via the configured propagator, records HTTP semantic-convention attributes, invokes optional request/response hooks, and records the span status from the HTTP response code, restoring the original send on _uninstrument(). Tech Stack — pure Python (src/opentelemetry/instrumentation/requests/__init__.py, ~630 lines), depending on opentelemetry-api, opentelemetry-instrumentation, opentelemetry-semantic-conventions, and opentelemetry-util-http from the same monorepo, plus requests itself as the instrumented target; built with hatchling. Code Quality — extensively tested with over 1,400 lines across three test files (test_requests_integration.py, test_requests_ip_support.py, test_user_agent_synthetic.py) covering header capture, IP recording, and synthetic User-Agent filtering, plus a benchmarks/ suite measuring instrumentation overhead. API Design — a single RequestsInstrumentor().instrument() call instruments every requests call in the process; request/response hooks and header-capture environment variables let teams add custom attributes without subclassing or wrapping the instrumentor.