Metadata-Version: 2.3
Name: fastapi-timer
Version: 0.1.2
Summary: Lightweight FastAPI middleware for request and downstream latency tracking
Author: Sachin Prabhu
Requires-Dist: fastapi>=0.141.1
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/sachinprabhu007/fastapi-timer
Project-URL: Repository, https://github.com/sachinprabhu007/fastapi-timer
Project-URL: Issues, https://github.com/sachinprabhu007/fastapi-timer/issues
Description-Content-Type: text/markdown

# ⏱️ fastapi-timer

> Lightweight FastAPI middleware for measuring API response time and downstream operation latency.

**Current version:** `0.1.0`

## ✨ Features

* ⏱️ Measure total API response time
* 🌐 Measure latency of any downstream operation
* 📊 See application vs downstream latency
* ⚡ Designed for async FastAPI applications
* 🪶 Lightweight and simple
* 🚫 No database required
* 🚫 No response headers

## 🚀 Why fastapi-timer?

When a FastAPI API is slow, it can be difficult to tell whether the time is being spent inside your application or waiting for a downstream service.

Without instrumentation, you might repeatedly write timing code:

```python
import time

start = time.perf_counter()

response = await client.get("https://example.com")

elapsed = (time.perf_counter() - start) * 1000
print(f"Downstream latency: {elapsed:.2f}ms")
```

`fastapi-timer` provides a simple way to do this:

```python
async with request.state.timer.track("downstream"):
    response = await client.get("https://example.com")
```

The middleware then logs:

```text
GET /example
  total: 460.98ms
  downstream: 459.97ms
  application: 1.01ms
```

## 📊 What does it measure?

* 🕐 **total** — complete API response time
* 🌐 **downstream** — time spent in a tracked downstream operation
* ⚙️ **application** — remaining application processing time

## 📦 Installation

Using `uv`:

```bash
uv add fastapi-timer
```

Using `pip` :

```bash
pip install fastapi-timer
```

## 🚀 Usage

Add the middleware to your FastAPI application:

```python
from fastapi import FastAPI, Request

from fastapi_timer import TimingMiddleware

app = FastAPI()

app.add_middleware(TimingMiddleware)
```

Track any downstream async operation:

```python
import httpx

@app.get("/example")
async def example(request: Request):
    timer = request.state.timer

    async with timer.track("downstream"):
        async with httpx.AsyncClient() as client:
            response = await client.get("https://example.com")

    return response.json()
```

## 🌤️ Example

A complete working example using a weather API is available in:

```text
examples/weather.py
```

The weather API is only an example. `fastapi-timer` can be used with **any downstream async operation**, including external APIs, microservices, and other network calls.

Run the example locally:

```bash
uv run uvicorn examples.weather:app --reload
```

Then request weather for a city:

```bash
curl "http://127.0.0.1:8000/weather?city=Chennai"
```

Example output:

```text
GET /weather
  total: 2445.45ms
  downstream: 777.26ms
  application: 1668.18ms
```

## 🛠️ Development

Install development dependencies:

```bash
uv sync
```

Run tests:

```bash
uv run pytest
```

Run tests with console output:

```bash
uv run pytest -s
```

Build the package:

```bash
uv build
```

## 📋 Requirements

* 🐍 Python 3.12+
* ⚡ FastAPI 0.141.1+

## 📄 License

[MIT License](LICENSE)

