Registry /
observability / opentelemetry-instrumentation-urllib
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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.464s · 24MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.454s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
URLLibInstrumentor
✓ from opentelemetry.instrumentation.urllib import URLLibInstrumentor
This example demonstrates how to set up the OpenTelemetry SDK with a console exporter and then automatically instrument `urllib` to trace an HTTP GET request. The trace will be printed to the console.
import os
from urllib import request
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.urllib import URLLibInstrumentor
# Configure OpenTelemetry SDK
provider = TracerProvider()
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Instrument urllib
URLLibInstrumentor().instrument()
# Make a request using urllib.request
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("my-urllib-request"):
try:
req = request.Request('http://httpbin.org/get')
response = request.urlopen(req)
print(f"Response Status: {response.getcode()}")
print(f"Response Data (first 100 chars): {response.read(100).decode()}")
except Exception as e:
print(f"Error during request: {e}")
opentelemetry-instrument --version
Debug
Known issues
gotchaInstrumentation must be enabled before the `urllib` module is first used. If `urllib` is imported or used before `URLLibInstrumentor().instrument()` is called, requests made prior to instrumentation will not be traced.fixEnsure `URLLibInstrumentor().instrument()` is called early in your application's lifecycle, typically during application startup before any `urllib` calls are made.
affects: All
gotchaThe library is currently in beta (`0.x.y` versions), meaning its API and produced telemetry (semantic conventions) may be subject to breaking changes between minor versions. This can impact dashboards or alerting built on specific attribute names.fixReview the `opentelemetry-python-contrib` changelog before upgrading to new beta versions. Consider pinning to specific beta versions if stability is critical.
affects: All `0.x.y` beta versions
gotchaTo capture HTTP request and response headers as span attributes, you must explicitly configure environment variables like `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST` and `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE`.fixSet these environment variables to a comma-delimited list of header names or a regex (e.g., `'.*'` for all headers). Use `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS` to redact sensitive header values.
affects: All
gotchaWhen using pre-forking web servers (e.g., Gunicorn with multiple workers), auto-instrumentation can lead to inconsistencies or break metrics generation due to issues with background threads and locks in child processes.fixConsider using programmatic auto-instrumentation in each worker, or restrict Gunicorn to a single worker for simpler setups. Refer to OpenTelemetry documentation on troubleshooting pre-fork issues.
affects: All
gotchaBy default, OpenTelemetry instrumentations do not provide a backend for storing, querying, or visualizing telemetry data. You need to integrate with an OpenTelemetry-compatible backend (e.g., Jaeger, Prometheus, commercial APMs) to utilize the collected traces.fixEnsure you have an OpenTelemetry Collector or an exporter configured to send data to your chosen observability backend.
affects: All
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry.
opentelemetry-sdkrequiredOpenTelemetry SDK for processing and exporting telemetry.
opentelemetry-semantic-conventionsrequiredStandardized attribute names for telemetry.
opentelemetry-util-httprequiredShared utilities for HTTP instrumentation.