aspirator

Python SDK for Aspirator, a minimal self-hosted error tracker. Zero dependencies, deliberately — an error tracker that drags in a dependency tree is one more thing that can break the app it is meant to be watching.

You need an Aspirator server to report to. This package on its own does nothing.

Install

pip install aspirator      # or: uv add aspirator

Use

import aspirator

aspirator.init()   # reads ASPIRATOR_DSN, ASPIRATOR_RELEASE, ASPIRATOR_ENVIRONMENT

try:
    charge(order)
except PaymentError as exc:
    aspirator.capture_exception(exc)

capture_exception also takes a plain string, for a problem you detected rather than caught. It is reported as an issue like any other, named and grouped by its text:

if not rows:
    aspirator.capture_exception("verifier returned no rows", level="warning")

init() also installs interpreter-level hooks, so a crash in a thread, an unretrieved asyncio task or a bare script is reported even where no framework wraps it.

Frameworks

from aspirator.integrations import django as aspirator_django

aspirator.init(integrations=[aspirator_django])

Django, FastAPI/Starlette and Celery are supported, plus a logging integration that forwards log lines and builds breadcrumbs. No middleware entry is needed for any of them — each patches the point that sits outside the whole chain, because middleware only ever sees what is raised below it.

Running under uvicorn? Flush on shutdown

@contextlib.asynccontextmanager
async def lifespan(app):
    yield
    aspirator.close()

app = FastAPI(lifespan=lifespan)

Events are sent by a background thread, and whatever it has not sent yet is flushed at exit. But docker stop sends SIGTERM, and SIGTERM kills a Python process without unwinding — so atexit never runs, and under uvicorn that loses the queue and the open metrics window on every deploy.

gunicorn does not need this (its worker exits normally) and neither does Celery (the integration is wired to the shutdown signals). It is uvicorn specifically, and all three were measured.

Also

Metrics (increment, gauge, timing), cron check-ins, breadcrumbs, request capture, and credential scrubbing by key.

Typed, all the way down

The package ships py.typed, and every public function names its keywords rather than taking **kwargs. That is the difference between an editor offering you one parameter and offering you all of them with their documentation — and between capture_exception(exc, transation="/orders") being a type error with a suggestion and being a line that silently does nothing.

aspirator.capture_exception(exc, level="warn")
#   Argument "level" has incompatible type "Literal['warn']";
#   expected Literal['debug', 'info', 'warning', 'error', 'fatal']

aspirator.init(is_error_skippable=lambda error: error.api_pth == "/health")
#   "CapturedError" has no attribute "api_pth"; maybe "api_path"?

aspirator.types is public and importable at runtime — Event, Level, User, Mechanism — so a filter or a processor of your own can be annotated against the payload it is handed.

Licence

MIT. Portions derived from sentry-python (MIT); see LICENSE.