Python + Flask

This guide covers adding debugger to a Python app using Flask. The setup takes two lines.

Flask official docs

Prerequisites

• Python 3.10 or later

Install

pip install ephem-debugger[flask]

Or with uv:

uv add ephem-debugger[flask]

Set up

Initialize debugger on your Flask app:

from flask import Flask
from ephem_debugger_py.middleware.flask import init_debugger, logger, close

app = Flask(__name__)
init_debugger(app, port=5000)
log = logger()

@app.route("/")
def index():
    log.info("home page hit")
    return {"status": "ok"}

if __name__ == "__main__":
    try:
        app.run(port=5000, debug=True)
    finally:
        close()

Two lines handle debugger setup:

1. init_debugger(app, port=5000) — capture HTTP requests and start the session
2. log = logger() — get a logger that writes to both stderr and the debugger store

What gets captured

• HTTP requests — method, path, status code, and latency
• Logging calls — any log.info(), log.error() call
• Unhandled exceptions — captured via Flask's teardown_request hook, which runs even when exceptions occur

Verify

Start your server:

flask run

Open another terminal and query:

npx dbg status

pnpm dlx dbg status

bun x dbg status

yarn dlx dbg status

npx dbg server console

pnpm dlx dbg server console

bun x dbg server console

yarn dlx dbg server console

Production safety

Guard the middleware for production:

import os
if os.getenv("DEBUG") == "1":
    init_debugger(app, port=5000)

Browser support

If your application serves HTML pages, the debugger automatically captures browser-side data. The middleware:

• Serves the browser client script at /_/d.js
• Handles browser log ingest at POST /_/d
• Auto-injects script tags into HTML responses before </body>

No additional setup is needed. Query browser data with:

npx dbg browser console

pnpm dlx dbg browser console

bun x dbg browser console

yarn dlx dbg browser console

npx dbg browser errors

pnpm dlx dbg browser errors

bun x dbg browser errors

yarn dlx dbg browser errors

npx dbg browser network

pnpm dlx dbg browser network

bun x dbg browser network

yarn dlx dbg browser network

npx dbg browser cookies

pnpm dlx dbg browser cookies

bun x dbg browser cookies

yarn dlx dbg browser cookies

npx dbg browser storage

pnpm dlx dbg browser storage

bun x dbg browser storage

yarn dlx dbg browser storage

Full example

See the complete working example at examples/python/flask.