hawkapi-otel

OpenTelemetry integration for HawkAPI — a plugin that initialises the OTel SDK on startup and a middleware that creates a server span per request, with full W3C trace-context propagation.

Works out of the box with a local OTLP collector. One-liner configs for Honeycomb, Grafana Cloud, Datadog, and Jaeger are listed below.

Quickstart

pip install hawkapi-otel

from hawkapi import HawkAPI
from hawkapi_otel import OTelPlugin, OTelMiddleware

app = HawkAPI()

app.add_plugin(
    OTelPlugin(
        service_name="my-app",
        service_version="1.0.0",
        endpoint="http://localhost:4317",
        protocol="grpc",
        insecure=True,
    )
)
app.add_middleware(OTelMiddleware)

Every request gets a server span with HTTP semantic-convention attributes. Unhandled exceptions are recorded on the current span.

OTelPlugin parameter reference

Sampler reference

Vendor recipes

Honeycomb

OTelPlugin(
    service_name="my-app",
    endpoint="https://api.honeycomb.io",
    protocol="http/protobuf",
    insecure=False,
    headers={"x-honeycomb-team": "YOUR_API_KEY"},
)

Grafana Cloud

OTelPlugin(
    service_name="my-app",
    endpoint="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp",
    protocol="http/protobuf",
    insecure=False,
    headers={"authorization": "Basic BASE64_ENCODED_INSTANCE_ID:TOKEN"},
)

Datadog (OTLP intake)

OTelPlugin(
    service_name="my-app",
    endpoint="https://api.datadoghq.com",
    protocol="http/protobuf",
    insecure=False,
    headers={"dd-api-key": "YOUR_DD_API_KEY"},
)

Jaeger (local)

OTelPlugin(
    service_name="my-app",
    endpoint="http://localhost:4317",
    protocol="grpc",
    insecure=True,
)

Development

# Clone and install in editable mode with dev extras
git clone https://github.com/Hawk-API/hawkapi-otel.git
cd hawkapi-otel
uv sync --extra dev

# Run tests
uv run pytest tests/ -q

# Lint
uv run ruff check .
uv run ruff format .

# Type-check
uv run pyright src/

License

MIT — Copyright (c) 2026 HawkAPI Contributors.