Registry /
observability / opentelemetry-instrumentation-urllib3
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.546s · 52.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.3s · import 0.516s · 50MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
URLLib3Instrumentor
✓ from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
This quickstart demonstrates how to set up OpenTelemetry with an OTLP gRPC exporter and instrument `urllib3` to trace HTTP requests. It initializes a `TracerProvider`, adds an `OTLPSpanExporter`, and then instruments `urllib3` before making an HTTP request. Remember to run an OpenTelemetry Collector or compatible backend to receive traces.
import os
import urllib3
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
# Configure OpenTelemetry TracerProvider
resource = Resource.create({"service.name": "my-urllib3-app"})
provider = TracerProvider(resource=resource)
trace.set_tracer_provider(provider)
# Configure OTLP Exporter
# Ensure an OTLP collector is running at os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317')
otlp_exporter = OTLPSpanExporter(
endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317'),
insecure=True # Use insecure for local testing if no TLS is configured
)
span_processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(span_processor)
# Initialize urllib3 instrumentation
URLLib3Instrumentor().instrument(
# Optional: Remove query parameters from span attribute for privacy/cardinality
url_filter=lambda url: url.split('?')[0]
)
# Perform an HTTP request with urllib3
http = urllib3.PoolManager()
print("Making a request to example.com...")
try:
response = http.request("GET", "http://www.example.com")
print(f"Request successful: {response.status}")
except Exception as e:
print(f"Request failed: {e}")
finally:
# It's good practice to shutdown the provider when the application exits
# This ensures all buffered spans are exported.
provider.shutdown()
print("OpenTelemetry provider shut down.")
Debug
Known issues
gotchaThe library is currently in beta (`0.61b0`), indicating that APIs and semantic conventions may still change between minor versions. While stable, users should anticipate potential adjustments in future releases.fixRefer to the official OpenTelemetry Python documentation and release notes for any breaking changes or updated best practices when upgrading.
affects: All 0.x.y versions (beta)
gotchaUnlike some OpenTelemetry auto-instrumentation approaches, `opentelemetry-instrumentation-urllib3` requires an explicit call to `URLLib3Instrumentor().instrument()` in your application code. It's not a 'zero-code' instrumentation via environment variables alone.fixEnsure `URLLib3Instrumentor().instrument()` is called early in your application's lifecycle, before `urllib3` HTTP requests are made, typically alongside your OpenTelemetry SDK setup.
affects: All versions
gotchaTo prevent capturing sensitive data or excessive telemetry from health checks, explicitly exclude URLs using the `OTEL_PYTHON_URLLIB3_EXCLUDED_URLS` or `OTEL_PYTHON_EXCLUDED_URLS` environment variables with comma-delimited regexes.fixSet `export OTEL_PYTHON_URLLIB3_EXCLUDED_URLS="/healthz,.*sensitive-data.*"` in your environment, or pass a `url_filter` callable during instrumentation.
affects: All versions
deprecatedEnvironment variables for capturing HTTP request and response headers (`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST`, `OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE`) and sanitizing them (`OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS`) are considered experimental and are subject to change according to OpenTelemetry specifications.fixStay updated with OpenTelemetry specification changes regarding HTTP header attributes. Use with caution in production environments where stability is critical.
affects: All versions
breakingAuto-instrumentation might cause dependency conflicts, especially with `urllib3` versions. If your application relies on `urllib3` 1.x and the auto-instrumentation tries to install or uses `urllib3` 2.x, it can break the application due to `PYTHONPATH` overrides.fixExplicitly pin `urllib3` versions in your `requirements.txt`. If using OpenTelemetry auto-instrumentation agents, configure them to avoid installing or overriding `urllib3` versions, or ensure a compatible version is used throughout.
affects: Versions interacting with `urllib3` 1.x and 2.x concurrently
gotchaIf you are using other HTTP client instrumentations (e.g., `opentelemetry-instrumentation-requests`), you might encounter duplicate spans or unexpected behavior, as `requests` internally uses `urllib3`. Consider disabling `opentelemetry-instrumentation-urllib3` in such cases to avoid redundant tracing.fixUse the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=urllib3` environment variable if another, higher-level HTTP client instrumentation (like `requests`) is preferred for tracing, to prevent `urllib3` from generating its own spans for the same outgoing calls.
affects: All versions when used with other HTTP client instrumentations
gotchaTraces generated by `opentelemetry-instrumentation-urllib3` (or any other instrumentation) require an OpenTelemetry collector or an OTLP-compatible endpoint to be running and accessible for successful export. If the exporter endpoint is unavailable, traces will be generated by the instrumentation but will not be visible outside the application.fixEnsure an OpenTelemetry collector is running and accessible at the configured `OTEL_EXPORTER_OTLP_ENDPOINT` (default is `localhost:4317`), or configure a different exporter if needed. Verify network connectivity and port availability for the exporter.
affects: All versions
gotchaTraces generated by the instrumentation library will not be visible if the configured OpenTelemetry Collector or OTLP endpoint is unavailable or unreachable, resulting in `StatusCode.UNAVAILABLE` errors during export. This is an SDK-level issue, but it directly impacts the successful collection of `urllib3` telemetry, leading to a lack of observable data.fixEnsure the OpenTelemetry Collector is running and accessible at the configured OTLP endpoint (default `localhost:4317`), or verify that the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable is correctly set and reachable.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
urllib3requiredThis library instruments urllib3. Ensure a compatible version is installed (e.g., versions 1.x or 2.x, but be aware of potential conflicts if your application explicitly relies on a specific major version).