Metadata-Version: 2.4
Name: fastapi-metrics
Version: 0.3.11
Summary: Zero-config metrics for FastAPI apps - perfect for solo devs and MVPs
Author-email: Arpit <arpit.thukral@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/arpit0515/fastapi-metrics
Project-URL: Repository, https://github.com/arpit0515/fastapi-metrics
Project-URL: Issues, https://github.com/arpit0515/fastapi-metrics/issues
Keywords: fastapi,metrics,observability,sqlite,monitoring,redis,prometheus,kubernetes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Framework :: FastAPI
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aioboto3>=11.0.0
Requires-Dist: asyncpg>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: aioboto3>=11.0.0; extra == "dev"
Requires-Dist: asyncpg>=0.27.0; extra == "dev"
Requires-Dist: rich>=13.0.0; extra == "dev"
Requires-Dist: uvicorn>=0.22.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.0.280; extra == "dev"
Dynamic: license-file

# FastAPI Metrics - Project Specification

## Project Vision
Zero-config metrics and observability for FastAPI apps targeting indie devs, startups, and no-code platforms. No Prometheus/Grafana infrastructure required.

## Core Value Proposition
- **5-minute setup**: One import, one line of code
- **No infrastructure**: SQLite/memory storage, no containers
- **Business metrics**: Track revenue, users, features - not just HTTP metrics
- **Query API**: JSON endpoints for custom dashboards
- **Cost tracking**: Auto-detect OpenAI/Anthropic API costs
- **No-code ready**: Retool/Bubble can consume the API directly

---

## Target Users
1. Indie developers building MVPs
2. Early-stage startups (pre-Series A)
3. No-code platform backends (Bubble, Retool, Make.com)
4. Developers prototyping without DevOps resources

---

## Technical Architecture

### Package Structure
```
fastapi-metrics/
├── fastapi_metrics/
│   ├── __init__.py
│   ├── core.py              # Main Metrics class
│   ├── middleware.py        # Request tracking middleware
│   ├── storage/
│   │   ├── base.py          # Storage interface
│   │   ├── memory.py        # In-memory storage
│   │   ├── sqlite.py        # SQLite storage
│   │   └── redis.py         # Redis storage (optional)
│   ├── collectors/
│   │   ├── http.py          # HTTP request metrics
│   │   ├── system.py        # CPU, memory, disk
│   │   ├── business.py      # Custom business metrics
│   │   └── cost.py          # LLM API cost tracking
│   ├── health/
│   │   ├── checks.py        # Health check implementations
│   │   └── endpoints.py     # Health endpoints
│   ├── query.py             # Metrics query engine
│   └── exporters/
│       ├── json.py          # JSON export
│       ├── prometheus.py    # Prometheus format
│       └── csv.py           # CSV export
├── tests/
├── examples/
├── docs/
└── pyproject.toml
```

---

## Phase 1: Core Functionality ⏳

### 1.1 Basic Setup & Middleware
- ✅ Main `Metrics` class initialization
- ✅ FastAPI app integration
- ✅ Request tracking middleware
- ✅ Response time calculation
- ✅ Status code tracking

### 1.2 Storage Backends
- ✅ Abstract storage interface
- ✅ In-memory storage (dict-based)
- ✅ SQLite storage with tables:
  - `http_requests` (timestamp, endpoint, method, status, latency_ms)
  - `custom_metrics` (timestamp, metric_name, value, labels)
  - `system_metrics` (timestamp, cpu, memory, disk)

### 1.3 HTTP Metrics Collection
- ✅ Requests per endpoint
- ✅ Requests per status code
- ✅ Requests per method
- ✅ Latency percentiles (p50, p95, p99)
- ✅ Error rate calculation
- ✅ Active requests counter

### 1.4 Query API Endpoints
- ✅ `GET /metrics` - Current snapshot (JSON)
- ✅ `GET /metrics/query` - Time-series queries
  - Query params: `from`, `to`, `metric`, `group_by`, `endpoint`
- ✅ `GET /metrics/endpoints` - Per-endpoint stats
- ✅ `GET /metrics/export?format=csv|prometheus`

---

## Phase 2: Health Checks & System Metrics ⏳

### 2.1 Health Check System
- ✅ Health check base class
- ✅ Built-in checks:
  - ✅ Database connectivity
  - ✅ Redis connectivity
  - ✅ Disk space
  - ✅ Memory usage
  - ✅ Custom check support
- ✅ Health endpoints:
  - ✅ `GET /health` - Simple status
  - ✅ `GET /health/live` - Liveness probe
  - ✅ `GET /health/ready` - Readiness probe with checks

### 2.2 System Metrics
- ✅ CPU usage tracking
- ✅ Memory usage tracking
- ✅ Disk usage tracking
- ✅ Uptime tracking
- ✅ System metrics endpoint

### 2.3 Additional
- ✅Make Redis storage first-class (not optional)
- ✅ Add proper K8s health checks (Phase 2 should be Phase 1)
- ✅ Add deployment examples for multi-instance setups
- ✅ Position as "lightweight alternative to Prometheus that scales"

---

## Phase 3: Business Metrics & Cost Tracking ⏳

### 3.1 Custom Business Metrics
- ✅ `metrics.track(name, value, **labels)` API
- ✅ Counter metrics
- ✅ Gauge metrics
- ✅ Histogram metrics
- ✅ Label/tag support for segmentation

### 3.2 LLM Cost Tracking
- ✅ Auto-detect OpenAI API calls
- ✅ Auto-detect Anthropic API calls
- ✅ Token usage tracking
- ✅ Cost calculation (using current pricing)
- ✅ Cost by model/endpoint
- ✅ `GET /metrics/costs` endpoint

---

## Phase 4: Advanced Features ⏳

### 4.1 Retention & Cleanup
- [ ] Configurable retention period
- [ ] Automatic data cleanup job
- [ ] Aggregation for old data (hourly → daily)

### 4.2 Alerting (Simple)
- [ ] Threshold-based alerts
- [ ] Webhook notifications
- [ ] Email notifications (optional)

### 4.3 Export Formats
- [ ] Prometheus format
- [ ] CSV export
- [ ] JSON export with timestamps


---

## Phase 5: Documentation & Examples ⏳

### 5.1 Documentation
- [ ] README with quick start
- [ ] Full API documentation
- [ ] Configuration guide
- [ ] Storage backend comparison
- [ ] Kubernetes deployment guide

### 5.2 Examples
- [ ] Basic FastAPI app
- [ ] With database health checks
- [ ] Custom business metrics
- [ ] LLM cost tracking
- [ ] Retool integration example
- [ ] No-code tool integration guide

### 5.3 Testing
- [ ] Unit tests (80%+ coverage)
- [ ] Integration tests
- [ ] Performance benchmarks

---

## API Design (MVP)

### Basic Usage
```python
from fastapi import FastAPI
from fastapi_metrics import Metrics

app = FastAPI()

# Minimal setup
metrics = Metrics(
    app,
    storage="sqlite://metrics.db",  # or "memory://"
    retention_hours=24,
)

# Track custom metrics anywhere
@app.post("/payment")
def payment(amount: float, user_id: int):
    metrics.track("revenue", amount, user_id=user_id)
    metrics.track("payment_count", 1)
    return {"status": "ok"}
```

### Query Examples
```
GET /metrics
GET /metrics/query?metric=revenue&from=24h&group_by=hour
GET /metrics/endpoints
GET /metrics/costs
GET /health/ready
```

---

## Key Decisions

### Storage Strategy
- **Default**: SQLite (single file, no setup)
- **Optional**: Redis (for distributed systems)
- **Fallback**: In-memory (testing/development)

### Data Model
- Store raw events initially
- Aggregate on query (Phase 1)
- Pre-aggregate for performance (Phase 4)

### Performance
- Async middleware (non-blocking)
- Background workers for aggregation
- Configurable batch writes
- Query result caching

---

## Success Metrics
- [ ] < 5 lines of code to set up
- [ ] < 1ms overhead per request
- [ ] Works with SQLite (no external deps)
- [ ] Query API returns in < 100ms
- [ ] Retool/Bubble integration works out-of-box

---

## Non-Goals (v1)
- ❌ Replace Prometheus/Grafana for large scale
- ❌ Distributed tracing
- ❌ Log aggregation
- ❌ APM-level profiling
- ❌ Built-in UI (JSON API only)

---

## Dependencies (Keep Minimal)
```toml
[dependencies]
fastapi = ">=0.100.0"
pydantic = ">=2.0.0"
aiosqlite = ">=0.19.0"  # Async SQLite
psutil = ">=5.9.0"      # System metrics
httpx = ">=0.24.0"      # For health checks (optional)
```

---

## Progress Tracker

### ✅ Completed
- Phase 1: Core functionality
- Phase 2: Health checks
- Phase 3: Business metrics
- Phase 4: Advanced features


### 🚧 In Progress
- Phase 5: Documentation

### ⏳ Todo
- Phase 6: Additional Features 
---

## Quick Start Command (Future)
```bash
pip install fastapi-metrics
```

## Development Setup (Future)
```bash
git clone https://github.com/yourusername/fastapi-metrics
cd fastapi-metrics
poetry install
poetry run pytest
```

---

## Notes & Decisions Log
- 2025-12-10: Initial spec created
- Target: Indie devs who want metrics without infrastructure
- Focus: Simplicity over enterprise features
- SQLite as default storage for zero-config experience

---

![Check errors in terminal](image.png)
