Python error tracking SDK for FastAPI and Django

RetraceKit ships a Python SDK for error tracking on FastAPI, Django, or plain asyncio backends. You install retrace-kit, call init, and exceptions become events in your project: issues, automatic incidents, AI summaries, and alerts.

Install from PyPI:

pip install retrace-kit

Package: retrace-kit on PyPI. Source: github.com/RetraceKit/sdk-python. Full setup: Python environment docs. Related reading on the blog.

From exception to event

The triage path is short:

1. An exception fires in your process (uncaught, thread, asyncio loop, or a manual capture_exception call).
2. The SDK builds an event: message, stack, release, environment, tags, breadcrumbs, session id, optional user.
3. RetraceKit fingerprints matching crashes into one issue.
4. When related issues share a route, release, or session, RetraceKit opens an incident so you triage one outage instead of a pile of tickets.

You read the AI brief, open the linked issues, and ship a fix against the release that lit up.

What you get

• Auto-capture for uncaught exceptions, threading errors, and asyncio loop exceptions after init
• Manual reporting with capture_exception
• Breadcrumbs, user context, and tags
• FastAPI and Django integrations
• Zero runtime dependencies in the core package
• Typed public API on Python 3.10+
• Client-side dedup that suppresses identical crashes for 30 seconds so a tight loop does not flood ingest
• A session ping on init so the process shows up in session-aware views

Captured exceptions land as events. You keep plans you already know: Free at 100,000 stored events, Plus at $5.99/month, Pro at $14.99/month.

Quick start

import os

from retrace_kit import init

init(api_key=os.environ["RETRACE_KIT_API_KEY"])

After init, uncaught errors in the main thread, worker threads, and the asyncio event loop become events automatically. For handled paths, call capture_exception, attach set_user / set_tag, and add breadcrumbs before the failure. api_key is enough. Optional release should come from importlib.metadata.version("your-package").

Init options

Option	Env var	Notes
api_key	RETRACE_KIT_API_KEY	Required. Blank key disables sending and logs a warning.
environment	RETRACE_KIT_ENVIRONMENT	Attached to every event (for example production).
enabled	-	Set False to keep hooks quiet in local runs.

The SDK sets tag runtime=python and a userAgent like Python/3.12.0 so you can filter backend traffic in the project inbox.

Dedup and sessions

A noisy worker that raises the same stack in a loop would burn storage if every raise became a new row. The Python SDK computes a dedup key from the error shape and last frame, then drops duplicates inside a 30-second window. After the window, the same crash can report again.

On init, the SDK allocates a sessionId and sends a session ping. Later events reuse that id, which feeds session correlation and incident rules that group by session.

FastAPI

import os

from fastapi import FastAPI

from retrace_kit import init
from retrace_kit.integrations.fastapi import setup_fastapi

init(api_key=os.environ["RETRACE_KIT_API_KEY"])
app = FastAPI()
setup_fastapi(app)

pip install retrace-kit[fastapi]

Unhandled server errors (5xx and uncaught exceptions) report as events with route breadcrumbs and the request URL. Client errors such as HTTPException(404) stay out of the inbox. You get FastAPI error tracking for real crashes without turning every missing asset into an issue.

Django

Add middleware in settings.py:

MIDDLEWARE = [
    # ...
    "retrace_kit.integrations.django.RetraceKitMiddleware",
]

Call init in settings.py or wsgi.py. Unhandled view exceptions become events; Http404 and PermissionDenied are ignored.

pip install retrace-kit[django]

Manual capture example

import os
from importlib.metadata import version

from retrace_kit import (
    add_breadcrumb,
    capture_exception,
    init,
    set_tag,
    set_user,
)

init(
    api_key=os.environ["RETRACE_KIT_API_KEY"],
    release=version("your-package"),
)

set_user({"id": "user_123"})
set_tag("plan", "pro")
add_breadcrumb(
    type="common",
    name="checkout",
    value="started",
)

try:
    checkout()
except Exception as error:
    capture_exception(error, context={"url": str(request.url)})

Breadcrumbs and tags travel with the event so the issue page shows what happened before the raise. See breadcrumbs and current user for how those fields show up in the app.

Verify the first event

1. Set RETRACE_KIT_API_KEY from project settings in the app.
2. Call init at process start (before you serve traffic).
3. Raise once: raise RuntimeError("retrace-kit smoke test"), or hit a FastAPI/Django route that throws.
4. Open Issues in the app. You should see an event with runtime=python and a Python userAgent.

If nothing arrives, check that the key is non-blank and enabled is not False. FastAPI and Django integrations attach the request URL; otherwise pass url in capture_exception context.

Why this matters for small teams

Backend crashes should land in the same triage flow as everything else you already track. One RetraceKit project turns Python exceptions into events, groups them into issues, and opens an incident when a release lights up related fingerprints. You keep Free at 100,000 stored events, or paid plans under $15/month with longer retention.

Links

• Python docs
• PyPI: retrace-kit
• Python SDK repository
• Incidents
• Plans
• Blog

FAQ

Which Python versions does RetraceKit support?

Python 3.10 and newer. The public API is typed and checked with mypy.

Does the Python SDK work with FastAPI and Django?

Yes. Install retrace-kit[fastapi] or retrace-kit[django]. FastAPI gets setup_fastapi for unhandled 5xx and exceptions with route breadcrumbs. Django gets RetraceKitMiddleware for view exceptions while ignoring Http404 and PermissionDenied.

Do I need extra packages for basic capture?

No. The core package has zero runtime dependencies. Framework extras are optional.

What happens to Python exceptions in RetraceKit?

Exceptions become events. Identical crashes group into issues. Related issues that share a route, release, or session open an automatic incident. AI summaries and third-party alerts work on those events.

What does RetraceKit ignore in FastAPI and Django?

Client-facing misses stay out of the inbox. FastAPI skips HTTPException for 4xx such as 404. Django skips Http404 and PermissionDenied. Unhandled 5xx and unexpected exceptions still become events.