📝 Add docstrings to codex/extend-performance-budget-configuration

Docstrings generation was requested by @shayancoin.

* #99 (comment)

The following files were modified:

* `scripts/ci/check_canary_budgets.py`

Author: coderabbitai[bot]

scripts/ci/check_canary_budgets.py

@@ -26,6 +26,14 @@ class BudgetResult:
     regression: Optional[float] = None
 
     def to_line(self) -> str:
+        """
+        Format the BudgetResult as a one-line status string.
+        
+        The string contains a status token (`OK` or `FAIL`), the budget name, the current value with unit, an optional previous value, and the threshold with unit and optional regression percentage. Numeric values are formatted with fixed decimal places (current and threshold to four decimals, regression as a percentage with two decimals).
+        
+        Returns:
+            A single-line human-readable status string, e.g. "[OK] p95-latency: current=123.4567 ms, previous=100.0000 ms (threshold=3000.0000 ms, regression=23.45%)"
+        """
         previous_part = f", previous={self.previous:.4f}{self.unit}" if self.previous is not None else ""
         regression_part = f", regression={self.regression:.2%}" if self.regression is not None else ""
         status = "OK" if self.passed else "FAIL"
@@ -36,12 +44,36 @@ def to_line(self) -> str:
 
 
 def _env(name: str, default: Optional[str] = None) -> Optional[str]:
+    """
+    Retrieve the value of an environment variable, returning a fallback when it's missing or empty.
+    
+    Parameters:
+        name (str): Environment variable name to read.
+        default (Optional[str]): Value to return if the environment variable is not set or is an empty string.
+    
+    Returns:
+        Optional[str]: The environment variable value, or `default` if the variable is unset or an empty string.
+    """
     value = os.getenv(name)
     return value if value not in (None, "") else default
 
 
 def query_prometheus(base_url: str, query: str, timestamp: float) -> float:
-    """Execute an instant Prometheus query and return the first scalar value."""
+    """
+    Execute an instant Prometheus query at a specific timestamp and return the first scalar sample value.
+    
+    Parameters:
+        base_url (str): Base URL of the Prometheus server (e.g., "http://prometheus:9090").
+        query (str): PromQL instant query to execute.
+        timestamp (float): UNIX timestamp (seconds) at which to evaluate the instant query.
+    
+    Returns:
+        float: The first scalar sample value from the query result.
+    
+    Raises:
+        SystemExit: If the HTTP request fails, the Prometheus response status is not "success",
+                    the query returns no data, or the result payload is malformed.
+    """
 
     encoded_query = urllib.parse.urlencode({"query": query, "time": f"{timestamp:.3f}"})
     url = f"{base_url.rstrip('/')}/api/v1/query?{encoded_query}"
@@ -76,6 +108,22 @@ def evaluate_budget(
     baseline_offset_seconds: float,
     unit_label: str,
 ) -> BudgetResult:
+    """
+    Evaluate a named budget by comparing the current Prometheus value to a baseline and determining threshold and regression compliance.
+    
+    Parameters:
+        name (str): Logical name for the budget result.
+        base_url (str): Prometheus base URL used to execute the query.
+        query (str): Prometheus instant query expression to evaluate.
+        unit_scale (float): Multiplier applied to raw Prometheus values to convert units (e.g., seconds to milliseconds).
+        threshold (float): Maximum acceptable current value for the budget to pass.
+        regression_tolerance (float): Maximum allowed relative increase ((current - previous) / previous) for the budget to pass.
+        baseline_offset_seconds (float): Seconds to subtract from the current timestamp to obtain the baseline evaluation time.
+        unit_label (str): Human-readable unit suffix included in the returned BudgetResult (e.g., " ms", " rate").
+    
+    Returns:
+        BudgetResult: Result containing the budget `name`, scaled `current` and `previous` values, `threshold`, `unit`, boolean `passed` indicating both threshold and regression compliance, and numeric `regression` (relative change) or `None` when previous value is zero.
+    """
     now = time.time()
     current_value_raw = query_prometheus(base_url, query, now)
     previous_value_raw = query_prometheus(base_url, query, now - baseline_offset_seconds)
@@ -102,6 +150,19 @@ def evaluate_budget(
 
 
 def query_tempo(base_url: str, query_json: str) -> dict:
+    """
+    Send a JSON search query to a Tempo instance and return the parsed JSON response.
+    
+    Parameters:
+        base_url (str): Base URL of the Tempo server (e.g., "http://tempo:9411").
+        query_json (str): JSON-formatted string to send as the search request body for the Tempo /api/search endpoint.
+    
+    Returns:
+        dict: Parsed JSON response from Tempo.
+    
+    Raises:
+        SystemExit: If the HTTP request fails (network error or other URL/IO error).
+    """
     data = query_json.encode("utf-8")
     request = urllib.request.Request(
         f"{base_url.rstrip('/')}/api/search", data=data, headers={"Content-Type": "application/json"}
@@ -114,6 +175,20 @@ def query_tempo(base_url: str, query_json: str) -> dict:
 
 
 def check_tempo_regressions(base_url: str, query: str, duration_budget_ms: float) -> BudgetResult:
+    """
+    Evaluate Tempo trace durations and compare the maximum observed duration against a provided duration budget.
+    
+    Parameters:
+        base_url (str): Base URL of the Tempo API.
+        query (str): Tempo search query payload as a JSON string.
+        duration_budget_ms (float): Allowed maximum trace duration in milliseconds.
+    
+    Returns:
+        BudgetResult: Result with name "tempo-trace-duration", `current` set to the maximum `durationMs` observed among returned traces, `previous` set to None, `threshold` equal to `duration_budget_ms`, `unit` set to " ms", and `passed` true if `current` is less than or equal to `threshold`.
+    
+    Raises:
+        SystemExit: If the Tempo response contains no traces or no trace durations.
+    """
     payload = query_tempo(base_url, query)
     traces = payload.get("traces", [])
     if not traces:
@@ -135,6 +210,14 @@ def check_tempo_regressions(base_url: str, query: str, duration_budget_ms: float
 
 
 def main() -> int:
+    """
+    Validate configured canary budgets by querying Prometheus (and optionally Tempo) and return an exit code.
+    
+    Reads environment variables for Prometheus and Tempo configuration and budget thresholds, evaluates latency and error budgets (and optional Tempo trace-duration budget), prints a one-line summary for each budget, and returns an exit code indicating overall status.
+    
+    Returns:
+        exit_code (int): 0 if Prometheus configuration is missing (validation skipped) or if all budgets pass; 1 if any budget failed.
+    """
     prom_url = _env("PROMETHEUS_URL")
     latency_query = _env("PROMETHEUS_LATENCY_QUERY")
     error_query = _env("PROMETHEUS_ERROR_RATE_QUERY")
@@ -198,4 +281,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())