stacklink 0.1.0__tar.gz → 0.2.0__tar.gz

{stacklink-0.1.0 → stacklink-0.2.0}/.claude/settings.local.json

@@ -7,7 +7,8 @@
       "Bash(pip3 install:*)",
       "Bash(PYTHONPATH=. python3:*)",
       "Bash(.venv/bin/python:*)",
-      "Bash(git:*)"
+      "Bash(git:*)",
+      "Bash(awk length > 88:*)"
     ]
   }
 }

{stacklink-0.1.0 → stacklink-0.2.0}/.codacy/logs/codacy-cli.log

@@ -666,3 +666,45 @@
 2026-04-12T21:25:02+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/pyproject.toml --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/pyproject.toml]
 2026-04-12T21:25:54+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
 2026-04-12T21:25:54+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/pyproject.toml --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/pyproject.toml]
+2026-04-12T21:42:18+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:42:18+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command args=[/Users/yevgenyokun/stacklink/stacklink/pyproject.toml] command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/pyproject.toml --format sarif]
+2026-04-12T21:42:25+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:42:25+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/docs/health.md --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/docs/health.md]
+2026-04-12T21:42:51+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:42:51+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/README.md --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/README.md]
+2026-04-12T21:42:56+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:42:56+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/README.md --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/README.md]
+2026-04-12T21:43:17+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:43:17+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/README.md --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/README.md]
+2026-04-12T21:43:26+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:43:26+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/README.md --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/README.md]
+2026-04-12T21:43:39+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:43:39+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command args=[/Users/yevgenyokun/stacklink/stacklink/README.md] command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/README.md --format sarif]
+2026-04-12T21:45:14+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:45:14+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/README.md --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/README.md]
+2026-04-12T21:54:30+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:54:30+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command args=[/Users/yevgenyokun/stacklink/stacklink/stacklink/metrics.py] command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/stacklink/metrics.py --format sarif]
+2026-04-12T21:54:30+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=trivy toolConfigPath=.codacy/tools-configs/trivy.yaml
+2026-04-12T21:54:31+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=lizard toolConfigPath=.codacy/tools-configs/lizard.yaml
+2026-04-12T21:54:31+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=opengrep toolConfigPath=.codacy/tools-configs/semgrep.yaml
+2026-04-12T21:54:32+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=pylint toolConfigPath=.codacy/tools-configs/pylint.rc
+2026-04-12T21:54:58+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:54:58+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/stacklink/metrics.py --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/stacklink/metrics.py]
+2026-04-12T21:54:58+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=pylint toolConfigPath=.codacy/tools-configs/pylint.rc
+2026-04-12T21:54:58+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=trivy toolConfigPath=.codacy/tools-configs/trivy.yaml
+2026-04-12T21:54:58+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=lizard toolConfigPath=.codacy/tools-configs/lizard.yaml
+2026-04-12T21:54:59+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=opengrep toolConfigPath=.codacy/tools-configs/semgrep.yaml
+2026-04-12T21:56:03+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:56:03+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/pyproject.toml --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/pyproject.toml]
+2026-04-12T21:56:06+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:56:06+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/stacklink/__init__.py --format sarif] args=[/Users/yevgenyokun/stacklink/stacklink/stacklink/__init__.py]
+2026-04-12T21:56:06+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=pylint toolConfigPath=.codacy/tools-configs/pylint.rc
+2026-04-12T21:56:07+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=trivy toolConfigPath=.codacy/tools-configs/trivy.yaml
+2026-04-12T21:56:07+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=lizard toolConfigPath=.codacy/tools-configs/lizard.yaml
+2026-04-12T21:56:07+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=opengrep toolConfigPath=.codacy/tools-configs/semgrep.yaml
+2026-04-12T21:56:11+01:00 [INFO] (codacy-cli-v2/cli-v2.go:27) Starting Codacy CLI version=1.0.0-main.375.sha.df55ffa (df55ffa) built at 2026-04-08T11:10:45Z
+2026-04-12T21:56:11+01:00 [INFO] (codacy-cli-v2/cmd/root.go:34) Executing CLI command args=[/Users/yevgenyokun/stacklink/stacklink/tests/test_metrics.py] command=analyze full_command=[/Users/yevgenyokun/Library/Caches/Codacy/codacy-cli-v2/1.0.0-main.375.sha.df55ffa/codacy-cli-v2 analyze /Users/yevgenyokun/stacklink/stacklink/tests/test_metrics.py --format sarif]
+2026-04-12T21:56:11+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=trivy toolConfigPath=.codacy/tools-configs/trivy.yaml
+2026-04-12T21:56:11+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool tool=lizard toolConfigPath=.codacy/tools-configs/lizard.yaml
+2026-04-12T21:56:11+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool toolConfigPath=.codacy/tools-configs/semgrep.yaml tool=opengrep
+2026-04-12T21:56:12+01:00 [INFO] (codacy-cli-v2/cmd/analyze.go:360) Config file found for tool toolConfigPath=.codacy/tools-configs/pylint.rc tool=pylint

{stacklink-0.1.0 → stacklink-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink
-Version: 0.1.0
+Version: 0.2.0
 Summary: Health checks, config validation, and structured logging for FastAPI
 Project-URL: Homepage, https://github.com/dressupdarling/stacklink
 Project-URL: Repository, https://github.com/dressupdarling/stacklink

{stacklink-0.1.0 → stacklink-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stacklink"
-version = "0.1.0"
+version = "0.2.0"
 description = "Health checks, config validation, and structured logging for FastAPI"
 readme = "README.md"
 requires-python = ">=3.10"

{stacklink-0.1.0 → stacklink-0.2.0}/stacklink/__init__.py

@@ -1,8 +1,9 @@
-"""stacklink — health checks, config validation, and structured logging for FastAPI."""
+"""stacklink — health, config, logging, and metrics for FastAPI."""
 
 from stacklink.config import Config, ConfigError, Field, StacklinkError
 from stacklink.health import HealthError, health
 from stacklink.logger import LoggerError, logger
+from stacklink.metrics import MetricsError, metrics
 
 __all__ = [
     "Config",
@@ -10,7 +11,9 @@ __all__ = [
     "Field",
     "HealthError",
     "LoggerError",
+    "MetricsError",
     "StacklinkError",
     "health",
     "logger",
+    "metrics",
 ]

stacklink-0.2.0/stacklink/metrics.py

@@ -0,0 +1,192 @@
+"""Request metrics tracking and reporting for FastAPI applications."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Awaitable, Callable
+from http import HTTPStatus
+
+from fastapi import FastAPI
+from fastapi.requests import Request
+from fastapi.responses import JSONResponse, Response
+
+from stacklink.config import StacklinkError
+
+CallNextFn = Callable[[Request], Awaitable[Response]]
+
+_ERROR_INFO: dict[int, dict[str, str]] = {
+    400: {
+        "meaning": "Bad Request",
+        "likely_cause": "Malformed request syntax or invalid parameters",
+        "quick_fix": "Validate request payload and query parameters before sending",
+    },
+    401: {
+        "meaning": "Unauthorized",
+        "likely_cause": "Missing or invalid authentication credentials",
+        "quick_fix": "Ensure a valid Authorization header or token is provided",
+    },
+    403: {
+        "meaning": "Forbidden",
+        "likely_cause": "Authenticated user lacks permission for this resource",
+        "quick_fix": "Check role and permission settings for the requesting user",
+    },
+    404: {
+        "meaning": "Not Found",
+        "likely_cause": "Client requested a URL that does not exist",
+        "quick_fix": "Check your route definitions and client request URLs",
+    },
+    405: {
+        "meaning": "Method Not Allowed",
+        "likely_cause": "HTTP method is not supported for this endpoint",
+        "quick_fix": "Verify the HTTP method matches the route definition",
+    },
+    408: {
+        "meaning": "Request Timeout",
+        "likely_cause": "The server timed out waiting for the client request",
+        "quick_fix": "Check network latency and increase client timeout settings",
+    },
+    422: {
+        "meaning": "Unprocessable Entity",
+        "likely_cause": "Request body failed validation rules",
+        "quick_fix": "Review the request schema and fix validation errors",
+    },
+    429: {
+        "meaning": "Too Many Requests",
+        "likely_cause": "Client exceeded the allowed request rate",
+        "quick_fix": "Implement backoff/retry logic and respect rate limit headers",
+    },
+    500: {
+        "meaning": "Internal Server Error",
+        "likely_cause": "Unhandled exception in a route handler",
+        "quick_fix": "Check application logs for traceback details",
+    },
+    502: {
+        "meaning": "Bad Gateway",
+        "likely_cause": "Upstream service returned an invalid response",
+        "quick_fix": "Verify that upstream services are running and reachable",
+    },
+    503: {
+        "meaning": "Service Unavailable",
+        "likely_cause": "Service is temporarily overloaded or under maintenance",
+        "quick_fix": "Check resource usage and consider scaling or restarting",
+    },
+    504: {
+        "meaning": "Gateway Timeout",
+        "likely_cause": "Upstream service did not respond in time",
+        "quick_fix": "Increase upstream timeout or investigate upstream latency",
+    },
+}
+
+
+def _error_detail(status_code: int, count: int) -> dict[str, object]:
+    """Build an error detail dict for a given status code and count."""
+    if status_code in _ERROR_INFO:
+        info = _ERROR_INFO[status_code]
+    else:
+        try:
+            phrase = HTTPStatus(status_code).phrase
+        except ValueError:
+            phrase = "Unknown Error"
+        info = {
+            "meaning": phrase,
+            "likely_cause": "An uncommon HTTP error occurred",
+            "quick_fix": "Inspect application logs for more details",
+        }
+    result: dict[str, object] = {"count": count}
+    result.update(info)
+    return result
+
+
+class MetricsError(StacklinkError):
+    """Raised when the metrics module encounters an error."""
+
+
+class MetricsRegistry:
+    """Registry for request metrics collection and the /metrics endpoint."""
+
+    def __init__(self) -> None:
+        """Initialize an empty metrics registry."""
+        self._start_time: float | None = None
+        self._request_count: int = 0
+        self._error_count: int = 0
+        self._response_times: list[float] = []
+        self._error_breakdown: dict[int, int] = {}
+
+    def register(self, app: FastAPI) -> None:
+        """Attach /metrics endpoint and request-tracking middleware to a FastAPI app."""
+        self._start_time = time.monotonic()
+        app.add_api_route("/metrics", self._metrics_endpoint, methods=["GET"])
+        registry = self
+
+        @app.middleware("http")
+        async def _track_requests(
+            request: Request,
+            call_next: CallNextFn,
+        ) -> Response:
+            """Track request count, errors, and response time."""
+            if request.url.path == "/metrics":
+                return await call_next(request)
+
+            start = time.monotonic()
+            response = await call_next(request)
+            elapsed = time.monotonic() - start
+
+            registry._request_count += 1
+            registry._response_times.append(elapsed)
+
+            if response.status_code >= 400:
+                registry._error_count += 1
+                code = response.status_code
+                registry._error_breakdown[code] = (
+                    registry._error_breakdown.get(code, 0) + 1
+                )
+
+            return response
+
+    def reset(self) -> None:
+        """Clear all collected metrics."""
+        self._request_count = 0
+        self._error_count = 0
+        self._response_times.clear()
+        self._error_breakdown.clear()
+
+    def _uptime(self) -> float:
+        """Calculate seconds since register() was called."""
+        if self._start_time is None:
+            return 0.0
+        return round(time.monotonic() - self._start_time, 1)
+
+    def _avg_response_time_ms(self) -> float:
+        """Calculate average response time in milliseconds."""
+        if not self._response_times:
+            return 0.0
+        avg_seconds = sum(self._response_times) / len(self._response_times)
+        return round(avg_seconds * 1000, 1)
+
+    def _error_rate(self) -> float:
+        """Calculate the ratio of error responses to total requests."""
+        if self._request_count == 0:
+            return 0.0
+        return round(self._error_count / self._request_count, 4)
+
+    def _build_error_breakdown(self) -> dict[str, dict[str, object]]:
+        """Build the error breakdown with details for each status code."""
+        breakdown: dict[str, dict[str, object]] = {}
+        for code, count in sorted(self._error_breakdown.items()):
+            breakdown[str(code)] = _error_detail(code, count)
+        return breakdown
+
+    async def _metrics_endpoint(self) -> JSONResponse:
+        """Handle GET /metrics -- return collected metrics."""
+        data: dict[str, object] = {
+            "uptime_seconds": self._uptime(),
+            "request_count": self._request_count,
+            "error_count": self._error_count,
+            "error_rate": self._error_rate(),
+            "avg_response_time_ms": self._avg_response_time_ms(),
+            "errors": self._build_error_breakdown(),
+        }
+        return JSONResponse(content=data, status_code=200)
+
+
+metrics = MetricsRegistry()

{stacklink-0.1.0 → stacklink-0.2.0}/stacklink-practices.md

@@ -82,7 +82,8 @@ bubble up to the user. Always catch and re-raise as a stacklink exception.
 StacklinkError          # base — catch this to catch anything from the library
 ├── ConfigError         # anything that goes wrong in the config module
 ├── LoggerError         # anything that goes wrong in the logger module
-└── HealthError         # anything that goes wrong in the health module
+├── HealthError         # anything that goes wrong in the health module
+└── MetricsError        # anything that goes wrong in the metrics module
 ```
 
 This means a user can catch `StacklinkError` broadly or `ConfigError` specifically.

stacklink-0.2.0/tests/test_metrics.py

@@ -0,0 +1,207 @@
+"""Tests for the metrics module."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from httpx import ASGITransport, AsyncClient
+
+from stacklink.metrics import MetricsRegistry
+
+
+@pytest.fixture
+def registry() -> MetricsRegistry:
+    return MetricsRegistry()
+
+
+@pytest.fixture
+def app(registry: MetricsRegistry) -> FastAPI:
+    application = FastAPI()
+
+    @application.get("/ok")
+    async def ok_route() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @application.get("/not-found")
+    async def not_found_route() -> JSONResponse:
+        return JSONResponse(status_code=404, content={"error": "not found"})
+
+    @application.get("/server-error")
+    async def server_error_route() -> JSONResponse:
+        return JSONResponse(status_code=500, content={"error": "boom"})
+
+    @application.get("/teapot")
+    async def teapot_route() -> JSONResponse:
+        return JSONResponse(status_code=418, content={"error": "teapot"})
+
+    registry.register(application)
+    return application
+
+
+class TestMetrics:
+    @pytest.mark.asyncio
+    async def test_metrics_returns_200(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """GET /metrics returns 200."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            resp = await c.get("/metrics")
+        assert resp.status_code == 200
+
+    @pytest.mark.asyncio
+    async def test_metrics_response_is_valid_json(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """Response body parses as JSON with expected keys."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            resp = await c.get("/metrics")
+        data = resp.json()
+        expected_keys = {
+            "uptime_seconds",
+            "request_count",
+            "error_count",
+            "error_rate",
+            "avg_response_time_ms",
+            "errors",
+        }
+        assert expected_keys <= set(data.keys())
+
+    @pytest.mark.asyncio
+    async def test_request_count_increments(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """Making 3 requests increments request_count to 3."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/ok")
+            await c.get("/ok")
+            await c.get("/ok")
+            resp = await c.get("/metrics")
+        assert resp.json()["request_count"] == 3
+
+    @pytest.mark.asyncio
+    async def test_error_count_tracks_4xx_and_5xx(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """4xx and 5xx responses increment error_count."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/not-found")
+            await c.get("/server-error")
+            resp = await c.get("/metrics")
+        assert resp.json()["error_count"] == 2
+
+    @pytest.mark.asyncio
+    async def test_error_rate_calculated(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """error_rate = error_count / request_count."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/ok")
+            await c.get("/ok")
+            await c.get("/not-found")
+            await c.get("/server-error")
+            resp = await c.get("/metrics")
+        data = resp.json()
+        assert data["error_rate"] == 2 / 4
+
+    @pytest.mark.asyncio
+    async def test_avg_response_time_is_positive(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """avg_response_time_ms > 0 after at least one request."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/ok")
+            resp = await c.get("/metrics")
+        assert resp.json()["avg_response_time_ms"] > 0
+
+    @pytest.mark.asyncio
+    async def test_error_breakdown_by_status_code(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """errors['404'] has count, meaning, likely_cause, quick_fix."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/not-found")
+            resp = await c.get("/metrics")
+        errors = resp.json()["errors"]
+        assert "404" in errors
+        entry = errors["404"]
+        assert entry["count"] == 1
+        assert "meaning" in entry
+        assert "likely_cause" in entry
+        assert "quick_fix" in entry
+
+    @pytest.mark.asyncio
+    async def test_metrics_endpoint_excludes_itself(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """/metrics requests are not counted in metrics."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/metrics")
+            await c.get("/metrics")
+            resp = await c.get("/metrics")
+        assert resp.json()["request_count"] == 0
+
+    @pytest.mark.asyncio
+    async def test_uptime_increases(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """uptime_seconds > 0 after a brief delay."""
+        await asyncio.sleep(0.15)
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            resp = await c.get("/metrics")
+        assert resp.json()["uptime_seconds"] > 0
+
+    @pytest.mark.asyncio
+    async def test_reset_clears_all_metrics(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """reset() zeroes all counters."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/ok")
+            await c.get("/not-found")
+            registry.reset()
+            resp = await c.get("/metrics")
+        data = resp.json()
+        assert data["request_count"] == 0
+        assert data["error_count"] == 0
+        assert data["avg_response_time_ms"] == 0.0
+        assert data["errors"] == {}
+
+    @pytest.mark.asyncio
+    async def test_error_rate_zero_when_no_requests(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """error_rate is 0.0 when no requests have been made."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            resp = await c.get("/metrics")
+        assert resp.json()["error_rate"] == 0.0
+
+    @pytest.mark.asyncio
+    async def test_unknown_error_code_has_generic_entry(
+        self, app: FastAPI, registry: MetricsRegistry
+    ) -> None:
+        """A 418 response gets a generic error entry."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as c:
+            await c.get("/teapot")
+            resp = await c.get("/metrics")
+        errors = resp.json()["errors"]
+        assert "418" in errors
+        entry = errors["418"]
+        assert entry["count"] == 1
+        assert "meaning" in entry
+        assert "likely_cause" in entry
+        assert "quick_fix" in entry