tracewise 0.1.0

Local tracing and debugging for FastAPI apps

TraceWise

TraceWise is a small tracing and debugging tool for FastAPI apps.

It records request spans to a local SQLite database and mounts a built-in viewer at /tracewise so you can inspect traces while developing.

Current scope:

• inbound FastAPI request tracing
• manual spans with tracewise.start_span(...)
• decorator-based spans with @tracewise.trace_span(...)
• span attributes and events
• optional log capture
• optional httpx client tracing with traceparent propagation
• local SQLite storage and a minimal embedded UI

This is aimed at local development and debugging. It is not trying to be a full APM or a hosted tracing backend.

Install

For local development in this repo:

uv sync --extra dev

Or with pip:

pip install -e .

If you want instrument_httpx=True, install the optional extra:

pip install -e ".[httpx]"

For a published package install, the same extra would be:

pip install "tracewise[httpx]"

Quick Start

from fastapi import FastAPI
import tracewise

app = FastAPI()

tracewise.init(
    app,
    capture_logs=True,
    instrument_httpx=True,
)


@app.get("/users")
async def list_users():
    async with tracewise.start_span("db.query", table="users", operation="SELECT"):
        pass

    tracewise.set_attribute("result.count", 2)
    tracewise.add_event("users.loaded")

    return {"users": []}

Once the app is running:

• make a request to one of your routes
• open /tracewise
• inspect the recorded trace tree

API Surface

Top-level helpers currently exposed by the package:

• tracewise.init(app, ...)
• tracewise.get_current_span()
• tracewise.start_span(name, **attributes)
• tracewise.trace_span(name, attributes=...)
• tracewise.set_attribute(key, value)
• tracewise.set_attributes({...})
• tracewise.add_event(name, **attributes)

Main init() options:

• db_path: path to the SQLite database file
• max_traces: max number of traces to keep
• enabled: turn tracing on or off
• capture_logs: attach a logging handler that records log events on the active span
• instrument_httpx: record outbound httpx requests and inject traceparent headers

If db_path is not provided, TraceWise stores data under ~/.tracewise/traces.db.

You can also disable tracing with:

TRACEWISE_ENABLED=false

Example App

A small example app lives in tests/testapp/main.py.

To run it with Docker:

docker compose -f docker/docker-compose.yml up --build

Then open:

• http://localhost:8000/health
• http://localhost:8000/users
• http://localhost:8000/orders
• http://localhost:8000/error
• http://localhost:8000/tracewise

Current Limitations

• FastAPI-specific for now
• local SQLite storage only
• viewer UI is intentionally minimal
• httpx tracing is optional and only applies if your app uses httpx
• not a replacement for OpenTelemetry or a hosted tracing stack

Development

Run the tests with:

uv run pytest