fastapi-loopguard 0.3.1__tar.gz → 0.4.1__tar.gz

fastapi_loopguard-0.4.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: fastapi-loopguard
+Version: 0.4.1
+Summary: Detect event-loop blocking in FastAPI/Starlette with per-request attribution
+Project-URL: Homepage, https://github.com/parhamdavari/fastapi-loopguard
+Project-URL: Documentation, https://github.com/parhamdavari/fastapi-loopguard#readme
+Project-URL: Repository, https://github.com/parhamdavari/fastapi-loopguard
+Project-URL: Issues, https://github.com/parhamdavari/fastapi-loopguard/issues
+Author: Parham
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,blocking,event-loop,fastapi,middleware,monitoring,performance,starlette
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: starlette<1.0,>=0.37.0
+Provides-Extra: all
+Requires-Dist: prometheus-client>=0.19.0; extra == 'all'
+Requires-Dist: structlog>=24.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: coverage>=7.4.0; extra == 'dev'
+Requires-Dist: fastapi>=0.110.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.19.0; extra == 'prometheus'
+Provides-Extra: stress
+Requires-Dist: locust>=2.20.0; extra == 'stress'
+Requires-Dist: uvicorn>=0.27.0; extra == 'stress'
+Provides-Extra: structlog
+Requires-Dist: structlog>=24.1.0; extra == 'structlog'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/loopguard-logo.webp" alt="LoopGuard" width="280" />
+</p>
+
+<p align="center">
+  <strong>Catch event-loop blocking in FastAPI with per-request attribution.</strong>
+</p>
+
+<p align="center">
+  <a href="https://badge.fury.io/py/fastapi-loopguard"><img src="https://badge.fury.io/py/fastapi-loopguard.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+---
+
+When a request blocks your event loop (via `time.sleep()`, blocking I/O, or CPU work), LoopGuard detects it **and tells you which endpoint caused it**.
+
+## Install
+
+```bash
+pip install fastapi-loopguard
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_loopguard import LoopGuardMiddleware
+
+app = FastAPI()
+app.add_middleware(LoopGuardMiddleware)
+```
+
+## Enforcement Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `"warn"` | Console warnings + headers | **Default** |
+| `"strict"` | HTTP 503 + error page | Development / CI |
+| `"log"` | Silent logging | Production |
+
+```python
+from fastapi_loopguard import LoopGuardConfig
+
+# Development: strict enforcement (503 on blocking)
+config = LoopGuardConfig(dev_mode=True)
+
+# Production: silent logging
+config = LoopGuardConfig(enforcement_mode="log")
+
+app.add_middleware(LoopGuardMiddleware, config=config)
+```
+
+## What You Get
+
+### Strict Mode
+Returns an educational 503 page that explains what went wrong and how to fix it:
+
+<p align="center">
+  <img src="assets/error-page-screenshot.png" alt="Strict mode error page" width="600" />
+</p>
+
+---
+
+### Warn Mode
+Adds diagnostic headers to every response for debugging:
+
+<p align="center">
+  <img src="assets/error-page-screenshot-endpoint.png" alt="Warn mode headers" width="600" />
+</p>
+
+---
+
+### Log Mode
+Writes structured logs with full request attribution:
+
+<p align="center">
+  <img src="assets/error-page-screenshot-console.png" alt="Console output" width="600" />
+</p>
+
+---
+
+<p align="center">
+  <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
+</p>

fastapi_loopguard-0.4.1/README.md

@@ -0,0 +1,86 @@
+<p align="center">
+  <img src="assets/loopguard-logo.webp" alt="LoopGuard" width="280" />
+</p>
+
+<p align="center">
+  <strong>Catch event-loop blocking in FastAPI with per-request attribution.</strong>
+</p>
+
+<p align="center">
+  <a href="https://badge.fury.io/py/fastapi-loopguard"><img src="https://badge.fury.io/py/fastapi-loopguard.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+---
+
+When a request blocks your event loop (via `time.sleep()`, blocking I/O, or CPU work), LoopGuard detects it **and tells you which endpoint caused it**.
+
+## Install
+
+```bash
+pip install fastapi-loopguard
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_loopguard import LoopGuardMiddleware
+
+app = FastAPI()
+app.add_middleware(LoopGuardMiddleware)
+```
+
+## Enforcement Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `"warn"` | Console warnings + headers | **Default** |
+| `"strict"` | HTTP 503 + error page | Development / CI |
+| `"log"` | Silent logging | Production |
+
+```python
+from fastapi_loopguard import LoopGuardConfig
+
+# Development: strict enforcement (503 on blocking)
+config = LoopGuardConfig(dev_mode=True)
+
+# Production: silent logging
+config = LoopGuardConfig(enforcement_mode="log")
+
+app.add_middleware(LoopGuardMiddleware, config=config)
+```
+
+## What You Get
+
+### Strict Mode
+Returns an educational 503 page that explains what went wrong and how to fix it:
+
+<p align="center">
+  <img src="assets/error-page-screenshot.png" alt="Strict mode error page" width="600" />
+</p>
+
+---
+
+### Warn Mode
+Adds diagnostic headers to every response for debugging:
+
+<p align="center">
+  <img src="assets/error-page-screenshot-endpoint.png" alt="Warn mode headers" width="600" />
+</p>
+
+---
+
+### Log Mode
+Writes structured logs with full request attribution:
+
+<p align="center">
+  <img src="assets/error-page-screenshot-console.png" alt="Console output" width="600" />
+</p>
+
+---
+
+<p align="center">
+  <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
+</p>

fastapi_loopguard-0.4.1/docs/CONFIGURATION.md

@@ -0,0 +1,129 @@
+# Configuration Reference
+
+All configuration options for `LoopGuardConfig`.
+
+## Quick Reference
+
+```python
+from fastapi_loopguard import LoopGuardConfig
+
+config = LoopGuardConfig(
+    # Enforcement
+    enforcement_mode="warn",      # "log" | "warn" | "strict"
+    dev_mode=False,               # Auto-escalates to strict when True
+
+    # Detection tuning
+    monitor_interval_ms=10.0,     # How often to check (ms)
+    threshold_multiplier=5.0,     # Blocking = lag > baseline × multiplier
+    fallback_threshold_ms=50.0,   # Threshold if calibration fails
+
+    # Cumulative detection (enabled by default)
+    cumulative_blocking_enabled=True,
+    cumulative_blocking_threshold_ms=200.0,
+    cumulative_window_ms=1000.0,
+
+    # Adaptive threshold (disabled by default)
+    adaptive_threshold=False,
+
+    # Integrations
+    prometheus_enabled=False,
+    log_blocking_events=True,
+)
+```
+
+---
+
+## Core Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | bool | `True` | Master switch. Set `False` to disable entirely. |
+| `enforcement_mode` | str | `"warn"` | How to respond: `"log"`, `"warn"`, or `"strict"` |
+| `dev_mode` | bool | `False` | Enables response headers. Auto-escalates to strict mode. |
+| `log_blocking_events` | bool | `True` | Log blocking events to console |
+| `exclude_paths` | frozenset | `{"/health", ...}` | Paths to skip monitoring |
+
+---
+
+## Detection Tuning
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `monitor_interval_ms` | float | `10.0` | Sentinel check frequency (ms) |
+| `threshold_multiplier` | float | `5.0` | Blocking detected when lag > baseline × this |
+| `calibration_iterations` | int | `100` | Samples during startup calibration |
+| `fallback_threshold_ms` | float | `50.0` | Used if calibration is unreliable |
+
+---
+
+## Cumulative Blocking Detection
+
+Catches "death by a thousand cuts" - many small blocks that add up.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cumulative_blocking_enabled` | bool | `True` | Enable cumulative detection |
+| `cumulative_blocking_threshold_ms` | float | `200.0` | Alert if total blocking exceeds this... |
+| `cumulative_window_ms` | float | `1000.0` | ...within this time window (ms) |
+
+**Example:** With defaults, alerts if blocking totals >200ms within any 1-second window.
+
+---
+
+## Adaptive Threshold
+
+Dynamically adjusts threshold based on observed latency. Useful for high-concurrency environments.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `adaptive_threshold` | bool | `False` | Enable adaptive mode |
+| `adaptive_window_size` | int | `1000` | Samples in sliding window |
+| `adaptive_percentile` | float | `0.95` | Percentile for baseline (0.5-0.99) |
+| `adaptive_min_samples` | int | `100` | Min samples before activation |
+| `adaptive_update_interval_ms` | float | `1000.0` | Recalculation frequency (ms) |
+
+---
+
+## Integrations
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prometheus_enabled` | bool | `False` | Expose Prometheus metrics |
+
+When enabled, exposes:
+- `loopguard_blocking_events_total` - Counter of blocking events
+- `loopguard_blocking_duration_ms` - Histogram of blocking durations
+
+---
+
+## Common Configurations
+
+### Development (strict enforcement)
+```python
+config = LoopGuardConfig(dev_mode=True)
+```
+
+### Production (silent monitoring)
+```python
+config = LoopGuardConfig(
+    enforcement_mode="log",
+    prometheus_enabled=True,
+)
+```
+
+### High-concurrency (adaptive threshold)
+```python
+config = LoopGuardConfig(
+    adaptive_threshold=True,
+    adaptive_percentile=0.99,
+)
+```
+
+### Sensitive detection (lower threshold)
+```python
+config = LoopGuardConfig(
+    monitor_interval_ms=5.0,
+    threshold_multiplier=3.0,
+    fallback_threshold_ms=30.0,
+)
+```

{fastapi_loopguard-0.3.1 → fastapi_loopguard-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-loopguard"
-version = "0.3.1"
+version = "0.4.1"
 description = "Detect event-loop blocking in FastAPI/Starlette with per-request attribution"
 readme = "README.md"
 license = "MIT"

{fastapi_loopguard-0.3.1 → fastapi_loopguard-0.4.1}/src/fastapi_loopguard/config.py

@@ -34,6 +34,10 @@ class LoopGuardConfig:
     log_blocking_events: bool = True
     prometheus_enabled: bool = False
 
+    # Enforcement mode: how aggressively to respond to blocking
+    # "log" = just log (production), "warn" = loud warnings, "strict" = 503 errors
+    enforcement_mode: str = "warn"
+
     # Adaptive threshold settings
     adaptive_threshold: bool = False
     adaptive_window_size: int = 1000
@@ -42,7 +46,7 @@ class LoopGuardConfig:
     adaptive_update_interval_ms: float = 1000.0
 
     # Cumulative blocking detection
-    cumulative_blocking_enabled: bool = False
+    cumulative_blocking_enabled: bool = True
     cumulative_blocking_threshold_ms: float = 200.0
     cumulative_window_ms: float = 1000.0
 
@@ -86,3 +90,10 @@ class LoopGuardConfig:
             raise ValueError(
                 "cumulative_window_ms cannot be less than monitor_interval_ms"
             )
+        # Enforcement mode validation
+        valid_enforcement_modes = {"log", "warn", "strict"}
+        if self.enforcement_mode not in valid_enforcement_modes:
+            raise ValueError(
+                f"enforcement_mode must be one of {valid_enforcement_modes}, "
+                f"got '{self.enforcement_mode}'"
+            )