aiogram-devtools

A live debugging toolbar for aiogram 3 bots. Attach it in one line, open a local web panel, and watch everything happening inside your bot in real time — updates, routing, filters, middleware timings, FSM state, dependency injection, SQL queries, outbound HTTP calls and errors.

Русская версия

Why

Debugging an aiogram bot usually means scattering print() and logging calls and guessing why an update didn't reach a handler. aiogram-devtools makes the bot's internals visible: which filters ran, which handler matched, how long each middleware took, what changed in the FSM, what SQL and HTTP fired — all correlated per update, streamed live to a browser.

It is observe-only. It hooks into aiogram's public extension points and a small instrumentation layer, and never changes how your bot behaves. Turn it off with a single flag and it adds zero overhead.

Features

• One-line setup — setup_devtools(dp, bot).
• Live web panel at http://127.0.0.1:8001 with a tab per concern.
• Per-update correlation — every record carries a trace_id, so you can follow one update through its whole lifecycle.
• Interactive diagrams — collapsible router tree, routing path, and an FSM state-transition timeline.
• Auto-detected integrations — SQLAlchemy and the common HTTP clients (httpx, aiohttp, requests, urllib). Missing libraries are skipped silently.
• Telegram traffic filtered out — your bot's own Bot API calls never clutter the HTTP tab.
• Secret redaction — the bot token and any keys you list are stripped before data leaves the process.
• Reversible — stopping devtools restores your dispatcher exactly as it was.
• Master switch — enabled=False makes it a complete no-op for production.

Install

pip install aiogram-devtools

# with optional integrations
pip install "aiogram-devtools[sqlalchemy,httpx]"

The browser panel loads Vue 3 and Tailwind from a CDN, so rendering the UI needs internet access.

Quick start

from aiogram import Bot, Dispatcher
from aiogram_devtools import setup_devtools

dp = Dispatcher()
bot = Bot(token="YOUR_TOKEN")

# Attach the toolbar.
setup_devtools(dp, bot)

# ... register your routers and handlers as usual ...

dp.run_polling(bot)

Run the bot and open http://127.0.0.1:8001.

To monitor SQL, register your engine:

dt = setup_devtools(dp, bot)
dt.add_sqlalchemy_engine(engine)   # sync Engine or AsyncEngine

A full demo bot exercising every feature lives in examples/demo_bot.py.

What the panel shows

How it works

Telegram update → Dispatcher → routers → middleware → handler
                       │
                  probes observe (never modify)
                       │
                  records (one trace_id per update)
                       │
                   EventBus ──┬── Store (bounded history + aggregates)
                              └── WebSocketHub → browser panel

• Probes are small, single-purpose instrumentation units installed in a fixed order (capture → middleware → filters → FSM → DI). Each wraps a public aiogram extension point and knows exactly how to undo itself.
• Collectors handle optional integrations: SQLAlchemy engine listeners and the HTTP client adapters. The HTTP collector auto-detects available clients, filters Telegram traffic, and de-duplicates layered clients so one request produces exactly one record.
• A contextvars-based trace ties every record produced while handling a single update to the same trace_id, with no plumbing through call signatures.
• The EventBus fans records out synchronously to the bounded Store and the WebSocketHub. A failing consumer is logged and never breaks the bot.
• The web server is built on aiohttp (already a dependency of aiogram), so the panel adds no heavy runtime dependency.

Because instrumentation is applied by walking the dispatcher's router tree at startup, your handlers are never rewritten, and stop() restores every wrapped internal to its original state.

Configuration

Pass options as keyword arguments to setup_devtools(...):

setup_devtools(
    dp, bot,
    host="127.0.0.1",
    port=8001,
    history_size=1000,        # records kept per type
    capture_update_json=True, # include raw update JSON
    redact_bot_token=True,
    secret_keys=["password", "api_key"],
    enable_sqlalchemy=True,
    enable_http=True,
    telegram_api_hosts=["api.telegram.org"],
    enabled=True,             # set False in production
)

Security

This is a development tool, not a production service. The panel has no authentication and binds to loopback by default. Don't expose it to the network or run it in production — use enabled=False there. The bot token and any configured secret_keys are redacted before leaving the process, but treat the panel as trusted-local only.

Requirements

• Python 3.11+
• aiogram 3.x, aiohttp 3.9+
• Optional: SQLAlchemy 2.x, httpx / requests (aiohttp and urllib are detected too)

Development

git clone https://github.com/jzombie971/aiogram-devtools
cd aiogram-devtools
pip install -e ".[dev,sqlalchemy,httpx]"
pytest

License

MIT