opentelemetry-instrumentation-httpx 0.65b0

Instrumenting all clients

When using the instrumentor, all clients will automatically trace requests.

import httpx
import asyncio
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

url = "https://example.com"
HTTPXClientInstrumentor().instrument()

with httpx.Client() as client:
    response = client.get(url)

async def get(url):
    async with httpx.AsyncClient() as client:
        response = await client.get(url)

asyncio.run(get(url))

The same package also supports httpx2 using the HTTPX2ClientInstrumentor:

import httpx2
import asyncio
from opentelemetry.instrumentation.httpx import HTTPX2ClientInstrumentor

url = "https://example.com"
HTTPX2ClientInstrumentor().instrument()

with httpx2.Client() as client:
    response = client.get(url)

async def get(url):
    async with httpx2.AsyncClient() as client:
        response = await client.get(url)

asyncio.run(get(url))

Instrumenting single clients

If you only want to instrument requests for specific client instances, you can use the HTTPXClientInstrumentor.instrument_client method.

import httpx
import asyncio
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

url = "https://example.com"

with httpx.Client() as client:
    HTTPXClientInstrumentor.instrument_client(client)
    response = client.get(url)

async def get(url):
    async with httpx.AsyncClient() as client:
        HTTPXClientInstrumentor.instrument_client(client)
        response = await client.get(url)

asyncio.run(get(url))

For httpx2 clients, use HTTPX2ClientInstrumentor.instrument_client:

import httpx2
from opentelemetry.instrumentation.httpx import HTTPX2ClientInstrumentor

with httpx2.Client() as client:
    HTTPX2ClientInstrumentor.instrument_client(client)
    response = client.get("https://example.com")

Uninstrument

If you need to uninstrument clients, there are two options available.

import httpx
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

HTTPXClientInstrumentor().instrument()
client = httpx.Client()

# Uninstrument a specific client
HTTPXClientInstrumentor.uninstrument_client(client)

# Uninstrument all clients
HTTPXClientInstrumentor().uninstrument()

Using transports directly

If you don’t want to use the instrumentor class, you can use the transport classes directly.

import httpx
import asyncio
from opentelemetry.instrumentation.httpx import (
    AsyncOpenTelemetryTransport,
    SyncOpenTelemetryTransport,
)

url = "https://example.com"
transport = httpx.HTTPTransport()
telemetry_transport = SyncOpenTelemetryTransport(transport)

with httpx.Client(transport=telemetry_transport) as client:
    response = client.get(url)

transport = httpx.AsyncHTTPTransport()
telemetry_transport = AsyncOpenTelemetryTransport(transport)

async def get(url):
    async with httpx.AsyncClient(transport=telemetry_transport) as client:
        response = await client.get(url)

asyncio.run(get(url))

For httpx2 transports, use SyncOpenTelemetryTransportHttpx2 and AsyncOpenTelemetryTransportHttpx2:

import httpx2
from opentelemetry.instrumentation.httpx import SyncOpenTelemetryTransportHttpx2

transport = httpx2.HTTPTransport()
telemetry_transport = SyncOpenTelemetryTransportHttpx2(transport)

with httpx2.Client(transport=telemetry_transport) as client:
    response = client.get("https://example.com")

Request and response hooks

The instrumentation supports specifying request and response hooks. These are functions that get called back by the instrumentation right after a span is created for a request and right before the span is finished while processing a response.

The hooks can be configured as follows:

from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

def request_hook(span, request):
    # method, url, headers, stream, extensions = request
    pass

def response_hook(span, request, response):
    # method, url, headers, stream, extensions = request
    # status_code, headers, stream, extensions = response
    pass

async def async_request_hook(span, request):
    # method, url, headers, stream, extensions = request
    pass

async def async_response_hook(span, request, response):
    # method, url, headers, stream, extensions = request
    # status_code, headers, stream, extensions = response
    pass

HTTPXClientInstrumentor().instrument(
    request_hook=request_hook,
    response_hook=response_hook,
    async_request_hook=async_request_hook,
    async_response_hook=async_response_hook
)

Or if you are using the transport classes directly:

import httpx
from opentelemetry.instrumentation.httpx import SyncOpenTelemetryTransport, AsyncOpenTelemetryTransport

def request_hook(span, request):
    # method, url, headers, stream, extensions = request
    pass

def response_hook(span, request, response):
    # method, url, headers, stream, extensions = request
    # status_code, headers, stream, extensions = response
    pass

async def async_request_hook(span, request):
    # method, url, headers, stream, extensions = request
    pass

async def async_response_hook(span, request, response):
    # method, url, headers, stream, extensions = request
    # status_code, headers, stream, extensions = response
    pass

transport = httpx.HTTPTransport()
telemetry_transport = SyncOpenTelemetryTransport(
    transport,
    request_hook=request_hook,
    response_hook=response_hook
)

async_transport = httpx.AsyncHTTPTransport()
async_telemetry_transport = AsyncOpenTelemetryTransport(
    async_transport,
    request_hook=async_request_hook,
    response_hook=async_response_hook
)