Tracing instrumentation

The Apitally SDK captures OpenTelemetry spans during request handling. This allows you to see exactly what happened during each request, including database queries, HTTP calls to external services, and custom operations. If you have an existing OpenTelemetry setup, the SDK automatically registers itself as a span processor with the global TracerProvider. Otherwise, it creates its own. Spans created within a captured request using the standard OpenTelemetry API or instrumentation libraries will be captured.

Instrument libraries

The SDK provides helper functions in apitally.otel to instrument popular libraries. These are thin wrappers around the official OpenTelemetry instrumentation packages, which need to be installed separately.

Library	Function	Required package
httpx	`instrument_httpx()`	`opentelemetry-instrumentation-httpx`
requests	`instrument_requests()`	`opentelemetry-instrumentation-requests`
SQLAlchemy	`instrument_sqlalchemy()`	`opentelemetry-instrumentation-sqlalchemy`
psycopg 3	`instrument_psycopg()`	`opentelemetry-instrumentation-psycopg`
psycopg2	`instrument_psycopg2()`	`opentelemetry-instrumentation-psycopg2`
asyncpg	`instrument_asyncpg()`	`opentelemetry-instrumentation-asyncpg`
mysql-connector-python	`instrument_mysql()`	`opentelemetry-instrumentation-mysql`
redis-py	`instrument_redis()`	`opentelemetry-instrumentation-redis`
PyMongo	`instrument_pymongo()`	`opentelemetry-instrumentation-pymongo`
botocore (AWS SDK)	`instrument_botocore()`	`opentelemetry-instrumentation-botocore`

To get started, first install the required packages for the libraries you want to instrument. For example, to instrument httpx and sqlalchemy:

pip install opentelemetry-instrumentation-httpx opentelemetry-instrumentation-sqlalchemy

uv add opentelemetry-instrumentation-httpx opentelemetry-instrumentation-sqlalchemy

poetry add opentelemetry-instrumentation-httpx opentelemetry-instrumentation-sqlalchemy

Then call the instrumentation functions at application startup. Some functions accept an optional client, connection or engine argument to instrument a specific instance instead of all instances globally.

from apitally.otel import instrument_httpx, instrument_sqlalchemy

instrument_httpx()
instrument_sqlalchemy(engine)

Create custom spans

For custom operations that aren’t covered by library instrumentation, you can create spans manually using the helpers provided by the SDK. These are thin wrappers around the standard OpenTelemetry API, which you can also use directly.

`@instrument` decorator

Use the @instrument decorator to automatically create a span for a function. It works with both sync and async functions:

from apitally.otel import instrument

@instrument
def process_order(order_id: int) -> None:
    ...

`span()` context manager

Use the span() context manager to trace code blocks within a function:

from apitally.otel import span

def checkout(cart_id: int) -> None:
    with span("validate_cart") as s:
        s.set_attribute("cart.id", cart_id)
        # Validation logic here
        ...

    with span("process_payment"):
        # Payment logic here
        ...

Capture handled exceptions

Apitally includes exceptions in request traces to help you diagnose server errors. Exceptions that propagate through your web framework are captured automatically. If your application catches an exception and handles it without re-raising it, call apitally.capture_exception() to include it in the current request trace.

import apitally

try:
    process_order()
except Exception as exc:
    apitally.capture_exception(exc)
    # Return an error response without re-raising the exception

SDK reference

Setup guides

Instrument libraries

Create custom spans

`@instrument` decorator

`span()` context manager

Capture handled exceptions

​Instrument libraries

​Create custom spans

​@instrument decorator

​span() context manager

​Capture handled exceptions

Instrument libraries

Create custom spans

`@instrument` decorator

`span()` context manager

Capture handled exceptions