📝 Add docstrings to codex/create-json-dashboards-and-configure-alerts

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`

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 a human-readable route label for the given request.
+    
+    Parameters:
+        request (Request): The incoming ASGI request from which to derive the route label.
+    
+    Returns:
+        str: The matched route's configured path if present (e.g. '/items/{id}'); otherwise the request URL path. If neither is available, returns "unknown".
+    """
     route = request.scope.get("route")
     if route and hasattr(route, "path") and route.path:
         return route.path
@@ -65,6 +74,18 @@ def _resolve_route_label(request: Request) -> str:
 
 class PrometheusInstrumentationMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):  # type: ignore[override]
+        """
+        Instruments HTTP requests with Prometheus metrics, forwards the request to the next handler, and returns its response.
+        
+        Skips instrumentation for the "/metrics" endpoint.
+        
+        Parameters:
+            request (Request): Incoming HTTP request.
+            call_next (Callable[[Request], Response]): Callable that processes the request and returns a Response.
+        
+        Returns:
+            Response: The response produced by the next handler.
+        """
         if request.url.path == "/metrics":
             return await call_next(request)
 

backend/api/metrics.py

@@ -64,7 +64,16 @@ def observe_http_request(
     status: str,
     duration_seconds: float,
 ) -> None:
-    """Record a single HTTP request observation."""
+    """
+    Record a single HTTP request observation for Prometheus metrics.
+    
+    Parameters:
+    	service (str): Logical name of the service handling the request (e.g., "api", "frontend").
+    	route (str): HTTP route or path being requested (e.g., "/users/{id}").
+    	method (str): HTTP method used for the request (e.g., "GET", "POST").
+    	status (str): HTTP response status code or status label (e.g., "200", "500").
+    	duration_seconds (float): Request duration in seconds to record in the latency histogram.
+    """
 
     http_requests_total.labels(
         service=service, route=route, method=method, status=status
@@ -78,4 +87,3 @@ def observe_lcp(*, app: str, seconds: float) -> None:
     """Record a Largest Contentful Paint 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."""
+    """
+    Accept a WebVitalPayload for the LCP metric, convert its value from milliseconds to seconds, and record the measurement.
+    
+    Parameters:
+        payload (WebVitalPayload): Web vital measurement; `name` must be "LCP", `value` is in milliseconds, and `app` identifies the source application.
+    
+    Returns:
+        result (dict[str, bool]): {"ok": True} on successful ingestion.
+    
+    Raises:
+        HTTPException: Raised with status 400 if `payload.name` is not "LCP".
+    """
 
     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,11 +9,26 @@
 
 
 def _get_sample(name: str, labels: dict[str, str]) -> float:
+    """
+    Retrieve the numeric value of a Prometheus metric sample identified by name and label set.
+    
+    Parameters:
+        name (str): Metric name to look up.
+        labels (dict[str, str]): Label key-value pairs used to identify the specific metric sample.
+    
+    Returns:
+        float: The metric's value as a float if found, otherwise 0.0.
+    """
     value = REGISTRY.get_sample_value(name, labels)
     return float(value) if value is not None else 0.0
 
 
 def test_lcp_ingest_records_histogram() -> None:
+    """
+    Verify posting an LCP web-vital increments the LCP count histogram for the specified app.
+    
+    Sends an LCP payload to the observability ingest endpoint and asserts the `web_vitals_lcp_count` metric for `app="frontend"` increases by 1.
+    """
     before = _get_sample("web_vitals_lcp_count", {"app": "frontend"})
 
     response = client.post(
@@ -38,6 +53,11 @@ def test_lcp_ingest_rejects_unsupported_metrics() -> None:
 
 
 def test_http_metrics_recorded_for_requests() -> None:
+    """
+    Verifies that an HTTP request to /healthcheck increments the Prometheus http_requests_total metric for the corresponding route labels.
+    
+    Reads the metric value for service="backend", route="/healthcheck", method="GET", status="200" before and after making a GET request to /healthcheck and asserts the metric increases by 1.
+    """
     route_labels = {
         "service": "backend",
         "route": "/healthcheck",
@@ -50,4 +70,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';
 
+/**
+ * Constructs the full endpoint URL used to report web-vitals metrics.
+ *
+ * When executed outside the browser (no `window`), returns `DEFAULT_ENDPOINT`. In a browser,
+ * the URL is composed from `NEXT_PUBLIC_BACKEND_PROTOCOL`, `NEXT_PUBLIC_BACKEND_HOST`,
+ * `NEXT_PUBLIC_BACKEND_PORT`, and `NEXT_PUBLIC_WEB_VITALS_ENDPOINT` environment variables with
+ * fallbacks to `window.location` and sensible defaults, formatted as `protocol//host[:port]endpoint`.
+ *
+ * @returns The endpoint URL string for reporting web-vitals
+ */
 function buildEndpoint(): string {
   if (typeof window === 'undefined') {
     return DEFAULT_ENDPOINT;
@@ -17,6 +27,14 @@ function buildEndpoint(): string {
   return `${protocol}//${host}${portSegment}${endpoint}`;
 }
 
+/**
+ * Sends a JSON metric payload to the given endpoint using a best-effort delivery strategy.
+ *
+ * Tries to use `navigator.sendBeacon` when available and falls back to a POST `fetch` with `keepalive`; network errors are ignored.
+ *
+ * @param endpoint - Destination URL to which the metric will be sent
+ * @param body - JSON-serialized metric payload
+ */
 function sendMetric(endpoint: string, body: string) {
   if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
     const blob = new Blob([body], { type: 'application/json' });
@@ -38,6 +56,15 @@ function sendMetric(endpoint: string, body: string) {
   });
 }
 
+/**
+ * Report the largest contentful paint (LCP) web-vital metric to the configured backend endpoint.
+ *
+ * If `metric.name` is not `'LCP'`, the metric is ignored. For LCP metrics, a JSON payload
+ * containing `name`, `value`, `app`, and `id` is constructed and transmitted using a
+ * best-effort delivery method.
+ *
+ * @param metric - The web-vital metric object; only metrics with `name === 'LCP'` are reported. The `value` and `id` properties are included in the reported payload.
+ */
 export function reportWebVitals(metric: Metric) {
   if (metric.name !== 'LCP') {
     return;
@@ -52,4 +79,4 @@ export function reportWebVitals(metric: Metric) {
   });
 
   sendMetric(endpoint, body);
-}
+}