Metadata-Version: 2.4
Name: fastapi-telemetry
Version: 0.0.2
Summary: Prometheus metrics middleware, circuit breaker listener, and metric helpers for FastAPI — zero project-specific dependencies
Project-URL: Homepage, https://github.com/acikabubo/fastapi-telemetry
Project-URL: Repository, https://github.com/acikabubo/fastapi-telemetry
Project-URL: Issues, https://github.com/acikabubo/fastapi-telemetry/issues
Author-email: Aleksandar Krsteski <acikabubo@gmail.com>
License: MIT
Keywords: circuit-breaker,fastapi,metrics,middleware,observability,prometheus
Classifier: Development Status :: 1 - Planning
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: prometheus-client>=0.24.1
Requires-Dist: starlette>=0.52.1
Provides-Extra: all
Requires-Dist: pybreaker>=1.4.1; extra == 'all'
Provides-Extra: circuit-breaker
Requires-Dist: pybreaker>=1.4.1; extra == 'circuit-breaker'
Provides-Extra: dev
Requires-Dist: fastapi>=0.115.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pybreaker>=1.4.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# fastapi-telemetry

> 📢 **Hobby Project Notice:** This is a research and learning project exploring FastAPI
> observability and Prometheus metrics best practices. Feel free to use it as a reference,
> report issues, or suggest improvements! Contributions and feedback are always welcome.

Prometheus metrics middleware, circuit breaker listener, and metric helpers for FastAPI —
zero project-specific dependencies (only Starlette and `prometheus-client`).

## Features

- `PrometheusMiddleware` — HTTP request duration, count, and in-flight metrics out of the
  box via injectable callbacks (no coupling to a specific metrics facade)
- `CircuitBreakerMetricsListener` — `pybreaker` listener that exports circuit breaker
  state, state-changes, and failure counts to Prometheus (optional dependency)
- `get_or_create_counter` / `get_or_create_gauge` / `get_or_create_histogram` — safe
  helpers that return an existing metric from the registry instead of raising
  `ValueError` on duplicate registration (useful with `--reload`)

## Installation

```bash
# Core (middleware + helpers)
pip install fastapi-telemetry

# With circuit-breaker support
pip install "fastapi-telemetry[circuit-breaker]"
```

## Quick start

```python
from fastapi import FastAPI
from fastapi_telemetry import PrometheusMiddleware, CircuitBreakerMetricsListener
from prometheus_client import make_asgi_app

app = FastAPI()

# Mount Prometheus scrape endpoint
app.mount("/metrics", make_asgi_app())

# Wire up the middleware with your own metric callbacks
app.add_middleware(
    PrometheusMiddleware,
    request_start_callback=lambda method, path: None,   # replace with your gauge.inc()
    request_end_callback=lambda m, p, s, d: None,       # replace with your histogram
    error_callback=lambda error_type, path: None,       # replace with your counter.inc()
)
```

### Circuit breaker

```python
from pybreaker import CircuitBreaker
from fastapi_telemetry import CircuitBreakerMetricsListener

cb = CircuitBreaker(
    name="redis",
    listeners=[CircuitBreakerMetricsListener(service_name="redis")],
)
```

## License

MIT
