{"id":910,"library":"opentelemetry-instrumentation-urllib3","title":"OpenTelemetry urllib3 Instrumentation","description":"This library provides automatic instrumentation for the `urllib3` HTTP client, enabling the collection of traces and metrics for HTTP requests made with `urllib3`. It's part of the OpenTelemetry Python Contrib repository and is currently in a beta development stage (`0.61b0`), with frequent updates.","status":"active","version":"0.61b0","language":"python","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","tracing","http","urllib3","instrumentation"],"install":[{"cmd":"pip install opentelemetry-instrumentation-urllib3 opentelemetry-sdk opentelemetry-exporter-otlp","lang":"bash","label":"Install package and core OpenTelemetry components"}],"dependencies":[{"reason":"This 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).","package":"urllib3","optional":false}],"imports":[{"symbol":"URLLib3Instrumentor","correct":"from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor"}],"quickstart":{"code":"import os\nimport urllib3\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor\n\n# Configure OpenTelemetry TracerProvider\nresource = Resource.create({\"service.name\": \"my-urllib3-app\"})\nprovider = TracerProvider(resource=resource)\ntrace.set_tracer_provider(provider)\n\n# Configure OTLP Exporter\n# Ensure an OTLP collector is running at os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317')\notlp_exporter = OTLPSpanExporter(\n    endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317'),\n    insecure=True # Use insecure for local testing if no TLS is configured\n)\nspan_processor = BatchSpanProcessor(otlp_exporter)\nprovider.add_span_processor(span_processor)\n\n# Initialize urllib3 instrumentation\nURLLib3Instrumentor().instrument(\n    # Optional: Remove query parameters from span attribute for privacy/cardinality\n    url_filter=lambda url: url.split('?')[0]\n)\n\n# Perform an HTTP request with urllib3\nhttp = urllib3.PoolManager()\nprint(\"Making a request to example.com...\")\ntry:\n    response = http.request(\"GET\", \"http://www.example.com\")\n    print(f\"Request successful: {response.status}\")\nexcept Exception as e:\n    print(f\"Request failed: {e}\")\nfinally:\n    # It's good practice to shutdown the provider when the application exits\n    # This ensures all buffered spans are exported.\n    provider.shutdown()\n    print(\"OpenTelemetry provider shut down.\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official OpenTelemetry Python documentation and release notes for any breaking changes or updated best practices when upgrading.","message":"The 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.","severity":"gotcha","affected_versions":"All 0.x.y versions (beta)"},{"fix":"Ensure `URLLib3Instrumentor().instrument()` is called early in your application's lifecycle, before `urllib3` HTTP requests are made, typically alongside your OpenTelemetry SDK setup.","message":"Unlike 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `export OTEL_PYTHON_URLLIB3_EXCLUDED_URLS=\"/healthz,.*sensitive-data.*\"` in your environment, or pass a `url_filter` callable during instrumentation.","message":"To 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Stay updated with OpenTelemetry specification changes regarding HTTP header attributes. Use with caution in production environments where stability is critical.","message":"Environment 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.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Explicitly 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.","message":"Auto-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.","severity":"breaking","affected_versions":"Versions interacting with `urllib3` 1.x and 2.x concurrently"},{"fix":"Use 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.","message":"If 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.","severity":"gotcha","affected_versions":"All versions when used with other HTTP client instrumentations"},{"fix":"Ensure 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.","message":"Traces 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Traces 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.61':44 'automat':7 'b0':45 'beta':41 'client':13 'collect':16 'contrib':34 'current':38 'develop':42 'enabl':14 'frequent':47 'http':12,22,52 'instrument':3,8,54 'librari':5 'made':24 'metric':20 'observ':50 'opentelemetri':1,32,49 'part':29 'provid':6 'python':33 'repositori':35 'request':23 'stage':43 'trace':18,51 'updat':48 'urllib3':2,11,26,53","created_at":"2026-03-29T06:07:18.357391+00:00","updated_at":"2026-04-16T17:44:40.793659+00:00","problems":{"verify_error":"error: Failed to parse: `opentelemetry-instrumentation-urllib3 opentelemetry-sdk opentelemetry-exporter-otlp`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `o`\nopentelemetry-instrumentation-urllib3 opentelemetry-sdk opentelemetry-exporter-otlp\n                           "},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.65b0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/open-telemetry/opentelemetry-python-contrib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opentelemetry-instrumentation-urllib3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":"verified"}}