OpenTelemetry urllib3 Instrumentation

Warnings

• gotcha 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.
  Fix: Refer to the official OpenTelemetry Python documentation and release notes for any breaking changes or updated best practices when upgrading.
• gotcha 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.
  Fix: Ensure `URLLib3Instrumentor().instrument()` is called early in your application's lifecycle, before `urllib3` HTTP requests are made, typically alongside your OpenTelemetry SDK setup.
• gotcha 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.
  Fix: Set `export OTEL_PYTHON_URLLIB3_EXCLUDED_URLS="/healthz,.*sensitive-data.*"` in your environment, or pass a `url_filter` callable during instrumentation.
• deprecated 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.
  Fix: Stay updated with OpenTelemetry specification changes regarding HTTP header attributes. Use with caution in production environments where stability is critical.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-urllib3 opentelemetry-sdk opentelemetry-exporter-otlp Install package and core OpenTelemetry components

Imports

• URLLib3Instrumentor

  from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor

Quickstart

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.")