OpenTelemetry urllib Instrumentation

Warnings

• gotcha Instrumentation 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.
  Fix: Ensure `URLLibInstrumentor().instrument()` is called early in your application's lifecycle, typically during application startup before any `urllib` calls are made.
• gotcha The 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.
  Fix: Review the `opentelemetry-python-contrib` changelog before upgrading to new beta versions. Consider pinning to specific beta versions if stability is critical.
• gotcha To 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`.
  Fix: Set 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.
• gotcha When 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.
  Fix: Consider 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.
• gotcha By 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.
  Fix: Ensure you have an OpenTelemetry Collector or an exporter configured to send data to your chosen observability backend.

Install

• pip install opentelemetry-instrumentation-urllib opentelemetry-sdk Install with SDK

Imports

• URLLibInstrumentor

  from opentelemetry.instrumentation.urllib import URLLibInstrumentor

Quickstart

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