octri (Python)

Error and performance monitoring for Python backends. Report errors out of Flask, FastAPI, or Django with original-source context per stack frame, time every request into a waterfall, and join each server error to the client SDK error for the same request through the W3C traceparent header. In the dashboard you see the full client and server stack under one trace.

Octri turns an OpenAPI spec into a documentation site, client SDKs for ten languages, an MCP server your AI assistant can call, and monitoring for the API behind them. This package is the Python monitoring runtime, and it works on its own: a generated Octri API SDK is not required. See octri.dev/monitoring.

Python 3.8 or newer. Pure standard library, with no required dependencies. The Python sibling of @octri/node.

Install

pip install octri

Setup

from octri import init

init(
    url="https://monitoring.example.com",   # your monitoring base URL
    token=os.environ["OCTRI_TOKEN"],         # your project ingest token
    environment="<your project id>",         # the dashboard project id
    release=os.environ.get("GIT_SHA"),       # optional
)

Hosted users can copy the project-scoped URL, token, and environment from the Monitoring connection settings (or its API). Pass token=None only when pointing at an open self-hosted ingest endpoint. Every request carries an idempotency key.

Standalone events

No generated API SDK is required to send your own events:

from octri import capture_event

capture_event(
    "checkout.completed",
    user={"id": customer.id},
    tags={"region": "eu-west", "plan": "growth"},
    context={"order_id": order.id, "total": order.total},
)

Delivery is best-effort and happens off the calling thread. Pass event_id to make a retried delivery idempotent.

Flask

from octri.flask import octri_flask

app = Flask(__name__)
octri_flask(app)   # observes unhandled request exceptions; nothing else to wire

FastAPI / Starlette

from octri.fastapi import OctriMiddleware

app = FastAPI()
app.add_middleware(OctriMiddleware)   # reports unhandled 500s, then re-raises

Django

# settings.py, after calling init(...) somewhere at startup
MIDDLEWARE = [
    # ...
    "octri.django.OctriMiddleware",
]

How linking works

The Octri client SDK sends a traceparent header on every request. Each integration reads it, captures the failing exception (with source context for each in-app frame), and reports it tagged octri.origin=server under the same traceId, so the client SDK error and this server error appear as one linked trace in the dashboard.

For compiled/minified clients, the dashboard pairs this with source maps / source bundles; the Python server frames already carry their original source inline.

Spans & the request waterfall

The middleware times each request. To see where time goes inside it, let Octri instrument common I/O automatically, or open spans yourself.

Automatic

octri.auto_instrument()                       # traces requests + urllib (outbound HTTP)
octri.instrument(cursor, ["execute"], op="db")  # your own DB client / util module, once
octri.instrument(cache, ["get", "set"], op="cache")

@octri.traced(op="fn")
def compute_totals(orders): ...

Every instrumented call (and every outbound HTTP request) becomes a sub-span under the current request, with no per-call code. Calls to your monitoring backend are never traced (no feedback loop).

Manual

with octri.span("orders.list", op="db"):
    rows = db.query(sql)

s = octri.start_span("render", op="view")
# ...work...
s.finish()

op ("db", "cache", "http", and so on) color-codes the bar in the dashboard waterfall.

Manual capture

from octri import capture_error, trace_from_header

try:
    ...
except Exception as exc:
    capture_error(exc, trace=trace_from_header(request.headers.get("traceparent")))
    raise

The rest of Octri

Monitoring runtimes

• Node
• Python
• Go
• Ruby
• Rust
• PHP
• Java
• Kotlin
• Swift
• Dart

More

• Documentation
• Pricing
• Changelog

MIT licensed.