OpenTelemetry urllib Instrumentation

opentelemetry-instrumentation-urllib is an OpenTelemetry instrumentation library that automatically traces outbound HTTP requests issued through Python’s standard-library urllib. Each request is wrapped in a client span carrying HTTP method, URL, and status-code attributes, and trace context is injected into outgoing headers so downstream services can continue the trace.

Part of the opentelemetry-python-contrib project, it supports request and response hooks for customizing spans and integrates with the standard OpenTelemetry API and SDK, giving even dependency-free, stdlib-only HTTP code full distributed-tracing coverage.

What You Get

• Automatic client spans for outbound urllib HTTP requests
• HTTP semantic-convention attributes (method, URL, status code) on each span
• Trace-context injection into outgoing request headers
• Configurable request and response hooks to enrich or filter spans
• Integration with the OpenTelemetry API/SDK and any configured exporter

Common Use Cases

• Tracing outbound calls from code that uses only the Python standard library
• Propagating trace context to downstream services over urllib requests
• Measuring latency and error rates of external HTTP calls made via urllib

Under The Hood

Architecture - The package lives at instrumentation/opentelemetry-instrumentation-urllib in the opentelemetry-python-contrib monorepo and ships a py.typed marker. Its URLLibInstrumentor patches urllib.request.OpenerDirector so each request opens a CLIENT-kind span, sets HTTP semantic-convention attributes, injects propagation headers, and invokes optional request_hook and response_hook callbacks around the span lifecycle.

Tech Stack - Pure Python, depending on opentelemetry-api (~=1.12), opentelemetry-instrumentation, opentelemetry-semantic-conventions, and opentelemetry-util-http for shared URL/header handling. It targets the standard-library urllib and emits through the host application’s configured OpenTelemetry SDK and exporter.

Code Quality - Maintained under the opentelemetry-python-contrib project (Apache-2.0) with shared CI, linting, type-checking, and a broad instrumentation test suite. The module is compact and delegates common HTTP logic to opentelemetry-util-http, keeping the urllib-specific patching narrow and well-scoped.

API Design - Enabling tracing is a single URLLibInstrumentor().instrument() call following the uniform contrib BaseInstrumentor pattern; the documented request_hook/response_hook signatures give a clean, typed extension point for enriching or filtering spans without subclassing.