documentation · v1.2.1
The snitchbot manual
Everything the library actually does, one page per idea. Pick a section — API reference for every public symbol, guides for integrations and tuning, cookbook for copy-paste recipes.
Guides
- Getting started Three steps — bot token, chat id, one init() call — and crashes flow into Telegram.
- FastAPI integration install(app) attaches middleware that scopes every request into snitchbot.
- Flask integration install(app) wires before_request, after_request, and a 5xx error handler into your Flask app.
- Litestar integration install(app) inserts an ASGI middleware and a global exception handler into your Litestar app.
- Configuring anomalies Tune RSS, CPU, FD, thread, and watchdog thresholds so alerts catch real problems without crying wolf.
- Reading the CSV export Load /export CSVs into pandas or duckdb — the vitals rolling buffer as a time series.
- Per-service topics (one bot, many services) Point snitchbot at a forum supergroup; the sidecar creates a topic per service automatically.
- Celery integration Initialize snitchbot in every Celery prefork worker after fork.
API reference
- init() Initialises the client and spawns the sidecar subprocess.
- notify() Send a custom notification to Telegram. Never raises.
- watch_slow() Decorator that emits a slow_call alert when a function exceeds threshold_ms.
- request_context() Context manager that attaches trace_id + extras to every event inside the block.
- setup_logging() Attach the snitchbot handler to a stdlib logger. One-liner integration.
- setup_structlog() Return a structlog processor that forwards WARNING+ events to Telegram.
- AnomalyConfig Top-level container bundling the seven anomaly detectors passed to init(anomaly=…).
- WatchdogConfig Asyncio event-loop watchdog — multi-threshold severity for stalled loops.
- RssAnomalyConfig Memory (RSS) anomaly detector with ceiling / spike / drop modes.
- CpuAnomalyConfig CPU% anomaly detector with ceiling / spike / drop modes.
- FdAnomalyConfig File-descriptor anomaly detector — leak and pool-collapse detection.
- ThreadAnomalyConfig Thread-count anomaly detector — thread leaks and worker-pool collapse.
- integrations.flask.init_app Initialize snitchbot once per Flask worker via a before_request guard.
- integrations.celery.install Initialize snitchbot in every Celery prefork worker via worker_process_init.
Cookbook
- Task completion ping Wrap a long-running job so failures and overruns ping you, without polluting the chat on every success.
- Encode version in the service name Stamp the running version into every alert by passing it through the service argument.
- Debug RSS spikes From a memory anomaly ping to a postmortem in three commands, without attaching a profiler.
- Track memory across subprocesses Make memory anomalies see your ffmpeg, Playwright, and multiprocessing children — not just the Python parent.
- Request-scoped context Attach trace_id, tenant, and request metadata once at the boundary; have every alert inside that scope carry it for free.
- Forking workers One sidecar shared across gunicorn, uvicorn, and Celery prefork workers — without double-spawning or losing the fork hook.