documentation · v0.1.0
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.
- Forum mode (one bot, many services) Run one bot in a forum supergroup; snitchbot creates a topic per service automatically.
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 five 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.
Cookbook
- Deploy-time notify Fire a single notify() from CI at the end of a deploy.
- Silence noisy warnings Collapse a 300-times-per-minute warning into a single alert with a counter.
- Group by tenant Attach tenant_id to every alert raised during a request, without threading it through every function.
- Health-check loop Alert once when your liveness probe flips to unhealthy — not every 30 seconds.