📝 Add docstrings to codex/create-json-dashboards-and-configure-alerts (#132)

Docstrings generation was requested by @shayancoin.

* #76 (comment)

The following files were modified:

* `backend/api/main.py`
* `backend/api/metrics.py`
* `backend/api/routes_observability.py`
* `backend/tests/test_observability_metrics.py`
* `frontend/src/app/reportWebVitals.ts`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: coderabbitai[bot]

backend/api/main.py

@@ -57,6 +57,15 @@ async def _ensure_sqlite_tables() -> None:
 
 
 def _resolve_route_label(request: Request) -> str:
+    """
+    Resolve the label to use for the incoming request's route.
+    
+    Parameters:
+        request (Request): The incoming Starlette/FastAPI request.
+    
+    Returns:
+        str: The route path from the request scope if present, otherwise the request URL path, or "unknown" if neither is available.
+    """
     route = request.scope.get("route")
     if route and hasattr(route, "path") and route.path:
         return route.path
@@ -65,6 +74,21 @@ def _resolve_route_label(request: Request) -> str:
 
 class PrometheusInstrumentationMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):  # type: ignore[override]
+        """
+        Instrument incoming HTTP requests with Prometheus metrics and forward them to the next handler.
+        
+        The middleware skips instrumentation for the "/metrics" path. For other requests it measures request duration, calls the downstream handler, and records an HTTP metric with service="backend", the resolved route label, HTTP method, status code, and duration in seconds. If the downstream handler raises an exception, the middleware records the metric with status "500" and re-raises the exception.
+        
+        Parameters:
+            request (Request): The incoming Starlette/FastAPI request.
+            call_next (Callable): The next ASGI/Starlette request handler to call.
+        
+        Returns:
+            Response: The response returned by the downstream handler.
+        
+        Raises:
+            Exception: Re-raises any exception raised by the downstream handler after recording the metric.
+        """
         if request.url.path == "/metrics":
             return await call_next(request)
 

backend/api/metrics.py

@@ -75,7 +75,12 @@ def observe_http_request(
 
 
 def observe_lcp(*, app: str, seconds: float) -> None:
-    """Record a Largest Contentful Paint measurement in seconds."""
+    """
+    Record the Largest Contentful Paint (LCP) value for an application.
+    
+    Parameters:
+    	app (str): Application identifier used as the `app` label.
+    	seconds (float): LCP measurement in seconds.
+    """
 
     web_vitals_lcp.labels(app=app).observe(seconds)
-

backend/api/routes_observability.py

@@ -21,7 +21,18 @@ class WebVitalPayload(BaseModel):
 
 @router.post("/web-vitals", status_code=status.HTTP_202_ACCEPTED)
 async def ingest_web_vitals(payload: WebVitalPayload) -> dict[str, bool]:
-    """Ingest Web Vital measurements emitted by the frontend."""
+    """
+    Process frontend web-vital measurements and record LCP metrics for observability.
+    
+    Parameters:
+        payload (WebVitalPayload): Web vital data from the frontend. Only metrics with `name == "LCP"` are accepted.
+    
+    Returns:
+        result (dict[str, bool]): A dictionary with {"ok": True} on successful ingestion.
+    
+    Raises:
+        HTTPException: If `payload.name` is not "LCP" (400 Bad Request with detail "Only LCP metrics are supported at this time").
+    """
 
     if payload.name != "LCP":
         raise HTTPException(
@@ -32,4 +43,4 @@ async def ingest_web_vitals(payload: WebVitalPayload) -> dict[str, bool]:
     # web-vitals reports timings in milliseconds; convert to seconds for Prometheus
     seconds = payload.value / 1000.0
     observe_lcp(app=payload.app, seconds=seconds)
-    return {"ok": True}
+    return {"ok": True}

backend/tests/test_observability_metrics.py

@@ -9,6 +9,16 @@
 
 
 def _get_sample(name: str, labels: dict[str, str]) -> float:
+    """
+    Retrieve a Prometheus metric sample value for the given metric name and labels.
+    
+    Parameters:
+        name (str): Metric name to query.
+        labels (dict[str, str]): Label set to match the metric sample.
+    
+    Returns:
+        float: The sampled metric value, or 0.0 if no matching sample exists.
+    """
     value = REGISTRY.get_sample_value(name, labels)
     return float(value) if value is not None else 0.0
 
@@ -27,6 +37,12 @@ def test_lcp_ingest_records_histogram() -> None:
 
 
 def test_lcp_ingest_rejects_unsupported_metrics() -> None:
+    """
+    Verifies that the web-vitals endpoint rejects unsupported metric types.
+    
+    Sends a POST request containing a CLS metric and asserts the response status is 400 with
+    detail "Only LCP metrics are supported at this time".
+    """
     response = client.post(
         "/observability/web-vitals",
         json={"name": "CLS", "value": 0.04},
@@ -38,6 +54,11 @@ def test_lcp_ingest_rejects_unsupported_metrics() -> None:
 
 
 def test_http_metrics_recorded_for_requests() -> None:
+    """
+    Verifies that a GET request to /healthcheck increments the Prometheus `http_requests_total` metric for the expected route labels.
+    
+    Reads the `http_requests_total` sample for service="backend", route="/healthcheck", method="GET", status="200" before and after performing the request and asserts the metric value increases by 1.
+    """
     route_labels = {
         "service": "backend",
         "route": "/healthcheck",
@@ -50,4 +71,4 @@ def test_http_metrics_recorded_for_requests() -> None:
 
     assert resp.status_code == 200
     after = _get_sample("http_requests_total", route_labels)
-    assert after == before + 1
+    assert after == before + 1

frontend/src/app/reportWebVitals.ts

@@ -3,6 +3,16 @@ import type { Metric } from 'next/app';
 const DEFAULT_ENDPOINT = '/observability/web-vitals';
 const APP_LABEL = process.env.NEXT_PUBLIC_WEB_VITALS_APP ?? 'frontend';
 
+/**
+ * Builds the full URL used to report web-vital metrics.
+ *
+ * Uses NEXT_PUBLIC_BACKEND_PROTOCOL, NEXT_PUBLIC_BACKEND_HOST, NEXT_PUBLIC_BACKEND_PORT, and
+ * NEXT_PUBLIC_WEB_VITALS_ENDPOINT environment variables when present; otherwise falls back to the
+ * current window.location values and configured defaults. When executed outside the browser
+ * (no `window`), returns the default endpoint path.
+ *
+ * @returns The full endpoint URL string, or the default endpoint path when running server-side.
+ */
 function buildEndpoint(): string {
   if (typeof window === 'undefined') {
     return DEFAULT_ENDPOINT;
@@ -17,6 +27,14 @@ function buildEndpoint(): string {
   return `${protocol}//${host}${portSegment}${endpoint}`;
 }
 
+/**
+ * Transmits a JSON payload to the given endpoint using a best-effort, fire-and-forget approach.
+ *
+ * Attempts to use `navigator.sendBeacon` with a JSON Blob; if that fails or is unavailable, falls back to a POST `fetch` with `keepalive`. Network errors are swallowed.
+ *
+ * @param endpoint - Destination URL for the metric
+ * @param body - JSON-stringified payload to send
+ */
 function sendMetric(endpoint: string, body: string) {
   if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
     const blob = new Blob([body], { type: 'application/json' });
@@ -38,6 +56,14 @@ function sendMetric(endpoint: string, body: string) {
   });
 }
 
+/**
+ * Sends the page's Largest Contentful Paint (LCP) metric to the configured observability endpoint.
+ *
+ * Only metrics with `metric.name === 'LCP'` are transmitted. The outgoing payload is JSON and includes
+ * the metric's `name`, `value`, `id`, and the application label.
+ *
+ * @param metric - The web-vitals `Metric` to evaluate and report (only LCP is reported)
+ */
 export function reportWebVitals(metric: Metric) {
   if (metric.name !== 'LCP') {
     return;
@@ -52,4 +78,4 @@ export function reportWebVitals(metric: Metric) {
   });
 
   sendMetric(endpoint, body);
-}
+}