timetracer 1.2.0

Time-travel debugging for FastAPI and Flask - record API cassettes, replay with mocked dependencies

Timetracer

Time-travel debugging for FastAPI and Flask — Record API requests, replay with mocked dependencies.

---

What is Timetracer?

Timetracer captures real API requests into portable cassettes and replays them with mocked dependencies (HTTP calls, database queries, Redis commands).

Record once. Replay anywhere. Debug faster.

Common use cases:

• Reproduce production bugs locally without access to external services
• Build regression tests from real traffic patterns
• Run demos offline with pre-recorded data
• Detect performance regressions between releases
• Compare behavior between different code versions

---

How It Works

Timetracer acts as middleware that intercepts your app's external calls:

                      RECORD MODE
┌──────────┐      ┌──────────────┐      ┌──────────────┐
│  Client  │ ───► │   Your App   │ ───► │   External   │
│  (curl)  │      │ + Timetracer │      │   APIs/DB    │
└──────────┘      └──────────────┘      └──────────────┘
                         │
                         ▼
                   ┌───────────┐
                   │  Cassette │  (saves everything)
                   │   .json   │
                   └───────────┘


                      REPLAY MODE
┌──────────┐      ┌──────────────┐       ╳ External APIs
│  Client  │ ───► │   Your App   │       ╳ (not called)
│  (curl)  │      │ + Timetracer │
└──────────┘      └──────────────┘
                         ▲
                         │
                   ┌───────────┐
                   │  Cassette │  (replays from here)
                   │   .json   │
                   └───────────┘

---

Installation

pip install timetracer[all]

Or install only what you need:

pip install timetracer[fastapi,httpx]    # FastAPI + HTTP
pip install timetracer[flask,requests]   # Flask + HTTP

---

Quick Start

FastAPI

from fastapi import FastAPI
from timetracer.integrations.fastapi import auto_setup

app = auto_setup(FastAPI())

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    async with httpx.AsyncClient() as client:
        return (await client.get(f"https://api.example.com/users/{user_id}")).json()

Flask

from flask import Flask
from timetracer.integrations.flask import auto_setup

app = auto_setup(Flask(__name__))

Record and Replay

# Record mode - captures all external calls
TIMETRACER_MODE=record uvicorn app:app
curl http://localhost:8000/users/123

# Replay mode - mocks external calls from cassette
TIMETRACER_MODE=replay \
  TIMETRACER_CASSETTE=./cassettes/2026-01-16/GET__users_{user_id}__abc.json \
  uvicorn app:app

---

Manual Setup

For more control over configuration:

import httpx
from fastapi import FastAPI
from timetracer import TraceConfig
from timetracer.integrations.fastapi import TimeTraceMiddleware
from timetracer.plugins import enable_httpx

app = FastAPI()

config = TraceConfig(
    mode="record",
    cassette_dir="./my-cassettes",
    errors_only=True,
)
app.add_middleware(TimeTraceMiddleware, config=config)

enable_httpx()

---

Configuration

All settings are controlled via environment variables:

Variable	Description	Default
TIMETRACER_MODE	off, record, replay	off
TIMETRACER_DIR	Cassette storage directory	./cassettes
TIMETRACER_CASSETTE	Path to cassette file (replay mode)	—
TIMETRACER_SAMPLE_RATE	Fraction of requests to record (0-1)	1.0
TIMETRACER_ERRORS_ONLY	Only record error responses	false
TIMETRACER_MOCK_PLUGINS	Plugins to mock during replay	all
TIMETRACER_LIVE_PLUGINS	Plugins to keep live during replay	none

---

Features

Category	Supported
Frameworks	FastAPI, Flask
HTTP Clients	httpx, requests
Databases	SQLAlchemy
Cache	Redis
Storage	Local filesystem, AWS S3
Tools	CLI, diff engine, HTML timeline, Dashboard

---

CLI

timetracer list --dir ./cassettes              # List all cassettes
timetracer show ./cassettes/GET__users.json    # Show cassette details
timetracer diff --a old.json --b new.json      # Compare two cassettes
timetracer timeline ./cassettes/GET__users.json --open  # Generate timeline
timetracer dashboard --dir ./cassettes --open  # Generate interactive dashboard
timetracer serve --dir ./cassettes --open      # Start live dashboard with replay

---

Dashboard

Browse and debug all recorded cassettes with the interactive dashboard:

# Static HTML dashboard (open in browser)
timetracer dashboard --dir ./cassettes --open

# Live dashboard with real-time replay
timetracer serve --dir ./cassettes --open

Features:

• Sortable table - Sort by time, method, status, duration
• Filters - Filter by method, status, duration, time range
• Error highlighting - Errors shown in red with warning icons
• Stack traces - View exception details and Python tracebacks
• Replay - One-click replay to see recorded request/response
• Raw JSON - Expandable view of full cassette data

---

Security

Timetracer automatically protects sensitive data:

• Removes Authorization, Cookie, and Set-Cookie headers
• Masks sensitive fields like password, token, api_key in request/response bodies
• Enforces a 64KB body size limit to prevent large data captures

---

Documentation

• Why Timetracer?
• Quick Start Guide
• Configuration Reference
• Dashboard Guide
• Plugin Guide
• SQLAlchemy Integration
• Flask Integration
• S3 Storage
• Cassette Search
• Security Best Practices

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.