Call once, as early as possible. Wires sys.excepthook, threading.excepthook, the asyncio handler, signal handlers (main thread only) and atexit; starts the watchdog daemon; registers a post-fork hook. Safe from any thread. Same-config repeat calls are a no-op. Runtime errors drop into degraded mode — only bad arguments and unsupported platforms raise.

If chat_id resolves to a forum-enabled supergroup AND the bot has can_manage_topics, the sidecar automatically creates one topic per service and routes every alert + command into the matching thread. Otherwise the sidecar sends every message to the chat without a thread id. Detection runs once at sidecar startup — there is no manual switch. See the Per-service topics guide.

Signature

def init(
    service: str,
    *,
    token: str | None = None,
    chat_id: str | int | None = None,
    anomaly=None,
    disabled: bool = False,
    role: str = "standalone",
    live_dashboard: bool = True,
    sample_interval_sec: int = 5,
    chart_width: int = 35,
) -> None

Parameters

NameTypeDescriptionDefault
servicestrShown in the chat header and every alert. Pick a stable name.required
tokenstr | NoneBot API token. Falls back to SNITCHBOT_TOKEN, then .env.None
chat_idstr | int | NoneTarget chat id. Falls back to SNITCHBOT_CHAT_ID, then .env.None
anomalyAnomalyConfig | bool | NoneNone / True = defaults, False = all off, or an AnomalyConfig.None
disabledboolKill-switch. Also honours SNITCHBOT_DISABLED=1.False
rolestrProcess role ("web", "worker", "beat")."standalone"
live_dashboardboolPin a dashboard message, rewrite on every vitals sample.True
sample_interval_secintpsutil sample cadence, [1, 60].5
chart_widthintWidth of ASCII charts rendered by /chart.35

Example

import snitchbot

snitchbot.init(
    "orders-api",
    role="web",
    live_dashboard=True,
)

# After this: crashes go to Telegram,
# /status /chart /export work in the chat.

Telegram shows: ▶ orders-api (web) started with a meta block of pid and UTC time.

Notes

Uvicorn / Gunicorn workers each spawn their own sidecar via the post-fork hook. Every worker appears in lifecycle alerts with its own pid.