https://github.com/alby-sh/alby-sdk-python
Official Alby error-tracking SDK for Python 3.8+ (Django, Flask, FastAPI)
https://github.com/alby-sh/alby-sdk-python
alby django error-monitoring error-tracking fastapi flask observability python sdk
Last synced: about 24 hours ago
JSON representation
Official Alby error-tracking SDK for Python 3.8+ (Django, Flask, FastAPI)
- Host: GitHub
- URL: https://github.com/alby-sh/alby-sdk-python
- Owner: alby-sh
- License: mit
- Created: 2026-04-20T01:19:29.000Z (7 days ago)
- Default Branch: main
- Last Pushed: 2026-04-20T10:45:19.000Z (7 days ago)
- Last Synced: 2026-04-25T03:38:36.890Z (2 days ago)
- Topics: alby, django, error-monitoring, error-tracking, fastapi, flask, observability, python, sdk
- Language: Python
- Homepage: https://alby.sh
- Size: 33.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# alby-report
[](https://pypi.org/project/alby-report/)
[](https://pypi.org/project/alby-report/)
[](https://pypi.org/project/alby-report/)
[](https://github.com/alby-sh/alby-sdk-python/actions/workflows/ci.yml)
[](./LICENSE)
Official [Alby](https://alby.sh) error-tracking SDK for Python.
Captures uncaught exceptions and anything you explicitly report, then ships them to your Alby project where an AI agent can auto-open a fix task.
Zero runtime dependencies. Python 3.8+.
## Install
```bash
pip install alby-report
```
## Use
```python
import os
import alby
alby.init(
dsn=os.environ['ALBY_DSN'], # https://@alby.sh/ingest/v1/
release='1.4.2',
environment='production',
)
# Uncaught exceptions are sent automatically (sys.excepthook + threading.excepthook).
# Manual report:
try:
do_thing()
except Exception as exc:
alby.capture_exception(exc)
# Non-error events:
alby.capture_message('Failed to acquire lease', level='warning')
# Enrich:
alby.set_user({'id': 'u_412', 'email': 'ada@example.com'})
alby.set_tag('region', 'eu-west-3')
alby.set_context('billing_tenant', {'plan': 'pro', 'seats': 12})
alby.add_breadcrumb({'type': 'http', 'message': 'GET /api/orders/42'})
# Decorator:
@alby.monitor
def charge_customer(customer_id: str) -> None:
...
# Before exit (e.g. in a short-lived CLI):
alby.flush(2000)
```
## Options
| Option | Type | Default | Notes |
|-------------------|----------------|-----------------|-------|
| `dsn` | `str` | - (required) | The DSN from your Alby app settings. |
| `release` | `str` | `''` | Your build version. Enables release tracking / auto-resolve. |
| `environment` | `str` | `$ALBY_ENV` or `'production'` | `production` / `staging` / `dev` / anything. |
| `sample_rate` | `float` | `1.0` | Fraction of events actually sent. |
| `platform` | `str` | `'python'` | Override auto-detection. |
| `server_name` | `str` | `socket.gethostname()` | Attached to every event. |
| `auto_register` | `bool` | `True` | Install `sys.excepthook` + `threading.excepthook` handlers. |
| `transport` | `Transport` | `HttpTransport` | Custom delivery (tests, batching, filesystem spool). |
| `debug` | `bool` | `False` | Log SDK diagnostics to stderr. |
| `max_breadcrumbs` | `int` | `100` | Ring buffer size. |
## Framework integrations
### Django
In `settings.py`:
```python
MIDDLEWARE = [
# ... Django's own middleware ...
'alby.integrations.django.AlbyMiddleware',
]
```
Initialise Alby early in your app setup (e.g. `settings.py` or `wsgi.py`).
### Flask
```python
from flask import Flask
from alby.integrations.flask import init_app as alby_init_app
app = Flask(__name__)
alby_init_app(app)
```
### FastAPI / Starlette
```python
from fastapi import FastAPI
from alby.integrations.fastapi import AlbyMiddleware
app = FastAPI()
app.add_middleware(AlbyMiddleware)
```
## Transport
* `urllib.request` under the hood (zero deps).
* Non-blocking: a bounded `queue.Queue(maxsize=100)` plus a daemon worker thread. `capture_*` only enqueues.
* Retries: 3 attempts at 1s / 5s / 15s backoff.
* Honours `Retry-After` on HTTP 429.
* Best-effort drain on interpreter exit via `atexit`.
For synchronous delivery, inject your own `Transport` via `alby.init(transport=...)`.
## Wire protocol
This SDK speaks the [Alby Ingest Protocol v1](./PROTOCOL_V1.md). If you're writing a new SDK (different runtime, different language) start there.
## Links
- Website: [alby.sh](https://alby.sh)
- Report issues: [GitHub Issues](https://github.com/alby-sh/alby-sdk-python/issues)
- Other SDKs: [alby-sdk-js](https://github.com/alby-sh/alby-sdk-js) · [alby-sdk-browser](https://github.com/alby-sh/alby-sdk-browser) · [alby-sdk-php](https://github.com/alby-sh/alby-sdk-php)
## License
MIT (c) Alby.