trazelet 0.1.0

A Lightweight, Zero-Configuration Observability Middleware for Python Backends

Trazelet

A Lightweight, Zero-Configuration Observability Middleware for Python Backends

Seamlessly integrates with FastAPI, Django, and Flask to deliver instant HTTP and API performance insights

Features • Quick Start • Documentation • Purpose • Contributing

---

🎯 What is Trazelet?

Trazelet is a high-performance, open-source Python plug-and-play middleware library that provides backend developers with instant HTTP and API performance analytics. It delivers immediate visibility into request latency without the complexity or overhead of traditional enterprise APM tools, and integrates seamlessly with Python web frameworks with zero configuration.

The Problem It Solves

Most developers don't know their API is slow until a user complains. Enterprise tools (like New Relic, Datadog) are too expensive or hard to set up for small-to-medium projects. Trazelet fills this gap by being local, private, and lightweight.

Why Trazelet?

• 🚀 Near-Zero Overhead: Non-blocking design with <0.2ms average latency impact
• 🔒 Privacy-First: All data stays on your machine. No cloud, no external services
• 🎯 Zero Configuration: Works out of the box with sensible defaults
• 🔌 Framework Agnostic: Works seamlessly with FastAPI, Django, and Flask
• ⚡ Production-Ready: Thread-safe, battle-tested architecture
• 📊 Built-in Performance Analytics: Actionable HTTP and API performance metrics out of the box
• 💻 Modern TUI Interface: Access real-time and historical analytics through a Rich-powered terminal UI

---

✨ Features

Core Capabilities

• ✅ Automatic Request Tracking: Captures latency, status codes, and API paths
• ✅ Non-Blocking Architecture: Queue-based buffering ensures zero impact on response times
• ✅ Batch Processing: Configurable batching for high-performance metric storage
• ✅ Thread-Safe: Verified with 100+ concurrent operations
• ✅ Invisible Middleware: Never crashes your application, graceful error handling
• ✅ Local Storage: SQLite (default) or PostgreSQL support
• ✅ Route Normalization: Automatically normalizes dynamic paths (/user/123 → /user/<id>)

Framework Support

• ✅ FastAPI: Clean ASGI middleware integration
• ✅ Django: Standard middleware pattern
• ✅ Flask: Proper request tracking with g object

Analytics & TUI Capabilities

• 📊 Real-time Performance Reports: Instant health overviews and detailed metric breakdowns via CLI.
• 📈 Endpoint Health Grading: Automated A/B/C/D grading for API endpoints based on performance.
• 🐢 Anomaly Detection: Quickly pinpoint slowest or most error-prone endpoints.
• 🎨 Rich Command-Line Interface: Interactive terminal output with tables, panels, and color-coding, powered by Rich.
• 📋 Flexible Output Formats: View analytics in human-readable tables, compact views, or machine-parseable JSON.

Core Performance Metrics

• Capture Latency: ~0.12ms average (non-blocking) ensures minimal impact.
• Concurrent Operations: Thread-safe design, verified with 100+ concurrent captures.
• Background Database Writes: Asynchronous processing with zero impact on the request path.
• Minimal Memory Footprint: Efficient queue-based buffering for low resource consumption.

---

🚀 Quick Start

Installation

# Core installation
pip install trazelet

Basic Usage

FastAPI

from fastapi import FastAPI
from trazelet.integrations.fastapi import FastAPIMiddleware
import trazelet

# Initialize Trazelet (uses SQLite by default)
trazelet.init()

app = FastAPI()
app.add_middleware(FastAPIMiddleware)

@app.get("/")
def read_root():
    return {"message": "Hello World"}

Django

# settings.py
MIDDLEWARE = [
    # ... other middleware ...
    "trazelet.integrations.django.DjangoMiddleware",
]

# Initialize Trazelet
import trazelet
trazelet.init()

Flask

from flask import Flask
from trazelet.integrations.flask import FlaskMiddleware
import trazelet

trazelet.init()

app = Flask(__name__)
app.wsgi_app = FlaskMiddleware(app=app)

@app.route("/")
def hello():
    return "Hello World!"

Custom Configuration

import trazelet

# Custom database and settings
trazelet.init(
    db_config={
        "db_url": "postgresql+psycopg2://user:pass@localhost:5432/trazelet",
        "echo": False
    },
    batch_size=100,           # Batch size for bulk inserts
    flush_interval=5.0,        # Flush interval in seconds
    max_workers=3,            # Background worker threads
    use_bulk_mode=True,       # Enable bulk insert mode
    logger_level="INFO"       # Logging level
    BUKCET_THRESHOLDS= [      # Set bucket threashold to classify for histogram in db
	25, 50, 100,
	200, 500, 1000,
	1500, 3000, 5000
    ]
)

---

📊 What Gets Tracked?

Trazelet automatically captures:

• API Path: Normalized route patterns (e.g., /user/<id> instead of /user/123)
• Latency: Request start/end times and elapsed duration
• Status Codes: HTTP response status codes
• Framework: Identifies which framework handled the request
• Timestamps: Precise request/response timestamps

Example Metrics:

/api/users/123     | 45ms  | 200 | FastAPI | 2025-01-15 10:30:00
/api/users/456     | 120ms | 200 | FastAPI | 2025-01-15 10:30:01
/api/orders/789    | 15ms  | 404 | FastAPI | 2025-01-15 10:30:02

---

🏗️ Architecture

Design Principles

1. Non-Blocking: All database operations happen in background threads
2. Thread-Safe: Uses ThreadPoolExecutor and thread-safe queues
3. Invisible: Never crashes your application, all errors are caught and logged
4. Efficient: Batch processing reduces database overhead

How It Works

Request → Middleware → Queue → Background Worker → Database
         (<0.2ms)    (O(1))   (Async)            (Batched)

1. Request arrives → Middleware captures start time
2. Response sent → Middleware captures end time and queues metric
3. Background worker → Processes queue in batches
4. Database → Bulk inserts for performance

---

📊 Real-time Analytics & TUI

Trazelet isn't just about capturing data; it's about making that data actionable. The Trazelet Text User Interface (TUI), powered by src/trazelet/tui/app.py, provides a rich, interactive command-line experience to instantly visualize and analyze your API's performance.

Leveraging the robust Analytics Engine described in the Architecture Report, the TUI transforms raw metrics into comprehensive, human-readable reports right in your terminal.

Key TUI Features:

• ⚡ Instant Performance Insights: Get real-time health overviews and detailed metric breakdowns.
• 🎨 Rich, Interactive Output: Uses Rich library for color-coded tables, panels, and progress spinners.
• 🎯 Endpoint-Level Granularity: Analyze individual endpoint performance (latency, errors, throughput, Apdex).
• 🔍 Anomaly Detection: Quickly identify slowest or most error-prone endpoints.
• 📋 Flexible Reporting: View metrics in detailed tables, compact summaries, or JSON for programmatic use.

⚙️ Configuring Database Connection via CLI

The trazelet configure-db command sets up your database connection following a strict precedence order:

1. TRACELET_DB_URL: Highest priority, used if set in your environment.
2. DATABASE_URL: Used if present, after prompting for confirmation.
3. Custom Environment Variable: Use --env-var <NAME> to save an environment variable name in ~/.trazelet/config.json. Trazelet will read the actual URL from os.environ[NAME] on subsequent runs.
4. Default SQLite: If no other sources are found, Trazelet defaults to an internal SQLite database (sqlite:///trazelet.db).

Use trazelet configure-db --reset to clear any previously saved custom environment variable name and re-evaluate the configuration.

Available Commands:

The Trazelet CLI (exposed via the trazelet command) offers the following powerful commands:

• Get an operational health overview of all monitored endpoints, including health grades and distribution.

  • trazelet status:

    trazelet status -d last_24h
    

• Dive into detailed analytics for all or specific endpoints, showing percentiles (P50, P95, P99), error rates, throughput, and Apdex scores.

  • trazelet describe:

  trazelet describe -d "7 days" --sort p99 -f json
  

• Highlight performance anomalies by listing the top N slowest or most error-prone endpoints.

  • trazelet top:

  trazelet top -m error -n 5
  

• View a comprehensive list of all active endpoints being monitored, with filtering options by framework or HTTP method.

  • trazelet list:

  trazelet list --framework fastapi
  

---

📖 Documentation

Configuration Options

Parameter	Type	Default	Description
db_config	dict	None	Database configuration (uses SQLite if not provided)
enabled	bool	True	Enable/disable Trazelet tracking
batch_size	int	50	Number of metrics to batch before flushing
flush_interval	float	5.0	Maximum seconds to wait before flushing queue data to DB
max_workers	int	1	Background worker threads (1 for SQLite, configurable for Postgres)
use_bulk_mode	bool	True	Enable bulk insert mode for performance
logger_level	str	"INFO"	Logging level: DEBUG, INFO, WARNING, ERROR

---

Database Configuration

SQLite (Default)

trazelet.init()  # Uses SQLite automatically

PostgreSQL

trazelet.init(
    db_config={
        "db_url": "postgresql+psycopg2://user:password@localhost:5432/dbname",
        "echo": False
    },
    max_workers=3  # Multiple workers for better throughput
)

Advanced Usage

Disable Trazelet Temporarily

trazelet.init(enabled=False)  # Disables tracking without removing middleware

Custom Logging

trazelet.init(logger_level="DEBUG")  # More verbose logging

Manual Flush

from trazelet.core.engine import get_engine

engine = get_engine()
engine.flush_buffer()  # Manually flush queued metrics

---

📝 License

This project is licensed under the MIT License.

---

💡 Built With Purpose

• The Vision: A high-velocity performance tracker tailored for the modern era of API wrappers and micro-services.
• Privacy by Design: Instant analytics that stay in your environment. We provide the logic; you keep the data.
• Zero-Config Core: Works out of the box with sensible defaults, while offering minimal config for those who need it.
• Flexible Persistence: Plug into your existing PostgreSQL for production or stay lightweight with SQLite by default.
• The Community: Built for the developers who prioritize lean, efficient tools. Thank you to everyone helping us keep this project focused and fast!

---

📚 Additional Resources

• Architecture report - Comprehensive technical audit
• Testing report - Test suite documentation
• Tracker - Development roadmap and feature tracking

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ Star us on GitHub • 📖 Documentation • 🐛 Report Bug