Python + FastAPI

This guide covers adding debugger to a Python API using FastAPI. The setup takes two lines.

FastAPI official docs

Prerequisites

• Python 3.10 or later

Install

pip install ephem-debugger[fastapi]

Or with uv:

uv add ephem-debugger[fastapi]

Set up

Add the middleware to your FastAPI app:

from fastapi import FastAPI
from ephem_debugger_py.middleware.fastapi import Middleware, logger, close

app = FastAPI()
app.add_middleware(Middleware, port=8000)
log = logger()

@app.get("/")
async def root():
    log.info("home page hit")
    return {"status": "ok"}

@app.on_event("shutdown")
async def shutdown():
    close()

Two lines handle debugger setup:

1. app.add_middleware(Middleware, port=8000) — 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 for every request
• Logging calls — any log.info(), log.error(), log.warning() call in your handlers

Verify

Start your server:

uvicorn app:app --reload

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

The middleware runs unconditionally. Guard it for production:

import os
if os.getenv("DEBUG") == "1":
    app.add_middleware(Middleware, port=8000)

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/fastapi.