Instrumentation Libraries

Next, we’ll learn how to instrument the libraries your application depends on. This guide walks through a small example application that calls a slow HTTP endpoint and demonstrates two approaches:

Manual (code-based) instrumentation, and
Automatic instrumentation using an OpenTelemetry instrumentation library.

Example application (uninstrumented)

A minimal Python app that performs an HTTP request via the requests library:

# app.py
import requests

def call_slow_api():
    url = "http://httpbin.org/delay/2"
    response = requests.get(url)
    return response.text

def main():
    print("Calling slow API...")
    result = call_slow_api()
    print("Done! Response length:", len(result))

if __name__ == "__main__":
    main()

The call to requests.get(url) makes a network call to a remote service. We want to measure how long that HTTP call takes and capture additional metadata about the request and response.

Manual instrumentation (explicit spans)

You can create spans manually around application code to record timing and metadata. This requires setting up a TracerProvider, span processor, and exporter, and creating spans with the tracer API:

# manual_instrumentation.py
import requests

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# SDK setup (so spans are recorded and exported)
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

def call_slow_api():
    # Manually create a span around the HTTP call
    with tracer.start_as_current_span("call_httpbin_delay"):
        url = "http://httpbin.org/delay/2"
        response = requests.get(url)
        return response.text

def main():
    with tracer.start_as_current_span("main_function_span"):
        print("Calling slow API...")
        result = call_slow_api()
        print("Done! Response length:", len(result))

if __name__ == "__main__":
    main()

A console exporter prints spans similar to the following (abbreviated):

{
  "name": "call_httpbin_delay",
  "kind": "SPAN_KIND_INTERNAL",
  "start_time": "2023-05-16T11:17:59.783592Z",
  "end_time": "2023-05-16T11:17:59.979302Z",
  "attributes": {},
  "resource": {
    "attributes": {
      "telemetry.sdk.language": "python",
      "telemetry.sdk.name": "opentelemetry",
      "telemetry.sdk.version": "1.31.1",
      "service.name": "unknown_service"
    }
  }
}

Manual instrumentation works well for targeted tracing, but applying it across many libraries and frameworks you do not own is time-consuming and error-prone.

The challenge: so many frameworks and libraries

The Python ecosystem (and other ecosystems) contains many frameworks and clients — web frameworks, HTTP clients, ORMs, messaging clients, and more. Instrumenting each call site manually across services quickly becomes unrealistic.

The image lists various frameworks and tools categorized under web frameworks, libraries and clients, ORMs and DB clients, messaging and RPC, and observability targets. It highlights the problem of having too many frameworks.

What we want:

Observability out of the box for commonly used libraries
Minimal effort for application developers
No vendor lock-in
Reuse across multiple apps and teams

OpenTelemetry Instrumentation Libraries

OpenTelemetry instrumentation libraries provide automatic tracing and/or metrics for popular third-party libraries. They are pre-built packages that apply language-specific techniques (in Python this is typically monkey patching) to wrap functions and capture telemetry with minimal or zero changes to your application code. Common targets:

HTTP clients: requests, httpx, aiohttp
Web frameworks: Flask, Django, FastAPI
ORMs and DB drivers: SQLAlchemy, database-specific drivers
Messaging and RPC: kafka-python, pika, celery
Cloud SDKs: boto3, etc.

Package naming convention (typical):

opentelemetry-instrumentation-<library-name>

The image lists five features of OTel Instrumentation Libraries: pre-built packages, language-specific techniques, zero-touch observability, comprehensive coverage, and standardized data.

Examples of instrumentation packages:

The image lists three OpenTelemetry instrumentation examples, each with a colorful numbered icon: requests for HTTP calls, Django for apps, and SQLAlchemy for database queries.

Auto-instrumenting the example using RequestsInstrumentor

Instead of adding spans manually around each HTTP call, enable the requests instrumentation package. Instrumentation libraries themselves use only the OpenTelemetry API — your application still configures the SDK and exporters.

# auto_instrument_requests.py
import requests

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
from opentelemetry.instrumentation.requests import RequestsInstrumentor

# SDK setup (needed so spans are recorded and exported)
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

# Auto-instrument the requests library (one line)
RequestsInstrumentor().instrument()

def call_slow_api():
    url = "http://httpbin.org/delay/2"
    response = requests.get(url)  # This call is automatically traced
    return response.text

def main():
    print("Calling slow API...")
    result = call_slow_api()
    print("Done! Response length:", len(result))

if __name__ == "__main__":
    main()

The instrumentation automatically creates spans for the HTTP client with semantic attributes (for example: http.method, http.url, http.status_code). A console-exported span for an instrumented HTTP GET might look like:

{
  "name": "HTTP GET",
  "kind": "SpanKind.CLIENT",
  "start_time": "2025-09-26T13:12:30.431667Z",
  "end_time": "2025-09-26T13:12:31.087899Z",
  "status": { "status_code": "ERROR" },
  "attributes": {
    "http.method": "GET",
    "http.url": "http://httpbin.org/delay/2",
    "http.status_code": 503
  },
  "resource": {
    "attributes": {
      "telemetry.sdk.language": "python",
      "telemetry.sdk.name": "opentelemetry",
      "telemetry.sdk.version": "1.14.0",
      "service.name": "unknown_service"
    }
  }
}

How the instrumentation library works (high level)

When you call RequestsInstrumentor().instrument(), the instrumentor finds and wraps the relevant methods in the requests package (for example, get, post, put, delete) and replaces them with instrumented wrappers. This is usually implemented via monkey patching. Each instrumented call typically:

Creates a client span using the OpenTelemetry API,
Executes the original requests call, and
Ends the span and attaches semantic attributes based on the response.

The image is a diagram explaining the functions of an instrumentation library, highlighting method interception, automatic span creation, and data captured without code changes.

Simplified illustration of monkey patching (conceptual)

# Conceptual pseudocode (not a real implementation)
original_get = requests.get

def instrumented_get(url, *args, **kwargs):
    # start a client span using the OpenTelemetry API
    # call original_get(url, *args, **kwargs)
    # set span attributes such as http.method, http.url, http.status_code
    # end the span
    return original_get(url, *args, **kwargs)

# Replace requests.get at runtime with the instrumented wrapper
requests.get = instrumented_get