philiprehberger-api-timer 0.3.0

Drop-in ASGI/WSGI middleware for endpoint timing with Server-Timing headers.

philiprehberger-api-timer

Drop-in ASGI/WSGI middleware for endpoint timing with Server-Timing headers.

Installation

pip install philiprehberger-api-timer

Usage

ASGI (FastAPI, Starlette)

from fastapi import FastAPI
from philiprehberger_api_timer import ASGITimerMiddleware

app = FastAPI()
app.add_middleware(ASGITimerMiddleware, slow_threshold_ms=500)

WSGI (Flask, Django)

from flask import Flask
from philiprehberger_api_timer import WSGITimerMiddleware

app = Flask(__name__)
app.wsgi_app = WSGITimerMiddleware(app.wsgi_app, slow_threshold_ms=500)

Custom Logger

import logging
from philiprehberger_api_timer import ASGITimerMiddleware

logger = logging.getLogger("my_api")
app.add_middleware(ASGITimerMiddleware, logger=logger, include_header=False)

Exclude Paths

from philiprehberger_api_timer import ASGITimerMiddleware

app.add_middleware(
    ASGITimerMiddleware,
    exclude_paths=["/health", "/metrics"],  # bypass timing entirely
)

Custom Header Name

from philiprehberger_api_timer import WSGITimerMiddleware

app.wsgi_app = WSGITimerMiddleware(app.wsgi_app, header_name="X-Request-Time")

Export to Prometheus / statsd via metric_callback

from philiprehberger_api_timer import ASGITimerMiddleware

def record(method: str, path: str, status: int, elapsed_ms: float) -> None:
    histogram.labels(method=method, path=path, status=status).observe(elapsed_ms)

app.add_middleware(ASGITimerMiddleware, metric_callback=record)

The callback fires once per non-excluded request after the response has been sent. Exceptions raised inside the callback are caught and logged so they cannot break the response.

What It Does

• Adds Server-Timing header to every response (e.g., Server-Timing: total;dur=42.5)
• Logs a WARNING for requests exceeding the slow threshold
• Zero configuration required — just add the middleware

API

Function / Class	Description
ASGITimerMiddleware(app, logger=None, slow_threshold_ms=500, include_header=True, header_name="Server-Timing", exclude_paths=None, metric_callback=None)	ASGI middleware
WSGITimerMiddleware(app, logger=None, slow_threshold_ms=500, include_header=True, header_name="Server-Timing", exclude_paths=None, metric_callback=None)	WSGI middleware
MetricCallback	Type alias for (method, path, status, elapsed_ms) -> None

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT