Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jcwalker3
|
82464f4054 | ||
|
jcwalker3
|
d7e69fbe77 | ||
 sysadmin
|
f80e3b33b0 | ||
 sysadminandClaude Opus 4.8
|
edd5f813b2 | ||
|
sysadminandClaude Opus 4.8
|
ecda200180 |
+1
-198
@@ -31,7 +31,7 @@ from typing import Any, Iterator, Sequence
|
||||
|
||||
import dependency_graph
|
||||
|
||||
SCHEMA_VERSION = 5
|
||||
SCHEMA_VERSION = 4
|
||||
|
||||
# Assignable work kinds only — raw monitoring incidents are never work items.
|
||||
WORK_KINDS = frozenset({"issue", "pr"})
|
||||
@@ -186,34 +186,6 @@ CREATE INDEX IF NOT EXISTS idx_dependency_edges_target
|
||||
ON dependency_edges(remote, org, repo, target_kind, target_number);
|
||||
CREATE INDEX IF NOT EXISTS idx_assignments_session ON assignments(session_id, status);
|
||||
CREATE INDEX IF NOT EXISTS idx_incident_gitea ON incident_links(gitea_org, gitea_repo, gitea_issue_number);
|
||||
|
||||
-- Model usage, token cost, latency, and performance events (#651)
|
||||
CREATE TABLE IF NOT EXISTS usage_events (
|
||||
usage_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
session_id TEXT,
|
||||
remote TEXT NOT NULL DEFAULT 'dadeschools',
|
||||
org TEXT NOT NULL DEFAULT '',
|
||||
repo TEXT NOT NULL DEFAULT '',
|
||||
project_id TEXT,
|
||||
role TEXT NOT NULL DEFAULT 'unknown',
|
||||
model TEXT NOT NULL DEFAULT 'unknown',
|
||||
issue_number INTEGER,
|
||||
pr_number INTEGER,
|
||||
stage TEXT NOT NULL DEFAULT 'unknown',
|
||||
input_tokens INTEGER,
|
||||
output_tokens INTEGER,
|
||||
total_tokens INTEGER,
|
||||
estimated_cost_usd REAL,
|
||||
latency_ms INTEGER,
|
||||
duration_ms INTEGER,
|
||||
status TEXT NOT NULL DEFAULT 'success',
|
||||
metadata TEXT,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_usage_events_scope ON usage_events(remote, org, repo);
|
||||
CREATE INDEX IF NOT EXISTS idx_usage_events_role_model ON usage_events(role, model);
|
||||
CREATE INDEX IF NOT EXISTS idx_usage_events_stage ON usage_events(stage);
|
||||
"""
|
||||
|
||||
|
||||
@@ -367,7 +339,6 @@ class ControlPlaneDB:
|
||||
self._migrate_incident_links_null_scope(conn)
|
||||
self._migrate_lease_lifecycle_columns(conn)
|
||||
self._migrate_session_ownership_columns(conn)
|
||||
self._migrate_usage_events_table(conn)
|
||||
conn.execute(
|
||||
"INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)",
|
||||
("schema_version", str(SCHEMA_VERSION)),
|
||||
@@ -547,174 +518,6 @@ class ControlPlaneDB:
|
||||
f"UPDATE incident_links SET {col} = '' WHERE {col} IS NULL"
|
||||
)
|
||||
|
||||
def _migrate_usage_events_table(self, conn: sqlite3.Connection) -> None:
|
||||
"""Create usage_events table and indexes if they do not exist (#651)."""
|
||||
conn.execute("""
|
||||
CREATE TABLE IF NOT EXISTS usage_events (
|
||||
usage_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
session_id TEXT,
|
||||
remote TEXT NOT NULL DEFAULT 'dadeschools',
|
||||
org TEXT NOT NULL DEFAULT '',
|
||||
repo TEXT NOT NULL DEFAULT '',
|
||||
project_id TEXT,
|
||||
role TEXT NOT NULL DEFAULT 'unknown',
|
||||
model TEXT NOT NULL DEFAULT 'unknown',
|
||||
issue_number INTEGER,
|
||||
pr_number INTEGER,
|
||||
stage TEXT NOT NULL DEFAULT 'unknown',
|
||||
input_tokens INTEGER,
|
||||
output_tokens INTEGER,
|
||||
total_tokens INTEGER,
|
||||
estimated_cost_usd REAL,
|
||||
latency_ms INTEGER,
|
||||
duration_ms INTEGER,
|
||||
status TEXT NOT NULL DEFAULT 'success',
|
||||
metadata TEXT,
|
||||
created_at TEXT NOT NULL
|
||||
);
|
||||
""")
|
||||
conn.execute("CREATE INDEX IF NOT EXISTS idx_usage_events_scope ON usage_events(remote, org, repo);")
|
||||
conn.execute("CREATE INDEX IF NOT EXISTS idx_usage_events_role_model ON usage_events(role, model);")
|
||||
conn.execute("CREATE INDEX IF NOT EXISTS idx_usage_events_stage ON usage_events(stage);")
|
||||
|
||||
def record_usage_event(
|
||||
self,
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
remote: str = "dadeschools",
|
||||
org: str = "",
|
||||
repo: str = "",
|
||||
project_id: str | None = None,
|
||||
role: str = "unknown",
|
||||
model: str = "unknown",
|
||||
issue_number: int | None = None,
|
||||
pr_number: int | None = None,
|
||||
stage: str = "unknown",
|
||||
input_tokens: int | None = None,
|
||||
output_tokens: int | None = None,
|
||||
total_tokens: int | None = None,
|
||||
estimated_cost_usd: float | None = None,
|
||||
latency_ms: int | None = None,
|
||||
duration_ms: int | None = None,
|
||||
status: str = "success",
|
||||
metadata: str | dict[str, Any] | None = None,
|
||||
created_at: str | None = None,
|
||||
) -> int:
|
||||
"""Record a model usage, token cost, latency, or stage performance event (#651)."""
|
||||
ts = created_at or _ts()
|
||||
meta_str: str | None = None
|
||||
if metadata is not None:
|
||||
from webui import console_redaction
|
||||
redacted_meta = console_redaction.redact_payload(metadata)
|
||||
if isinstance(redacted_meta, str):
|
||||
meta_str = redacted_meta
|
||||
else:
|
||||
try:
|
||||
meta_str = json.dumps(redacted_meta, default=str)
|
||||
except Exception:
|
||||
meta_str = str(redacted_meta)
|
||||
|
||||
if total_tokens is None and (input_tokens is not None or output_tokens is not None):
|
||||
total_tokens = (input_tokens or 0) + (output_tokens or 0)
|
||||
|
||||
with self._tx(immediate=True) as conn:
|
||||
cursor = conn.execute(
|
||||
"""
|
||||
INSERT INTO usage_events (
|
||||
session_id, remote, org, repo, project_id, role, model,
|
||||
issue_number, pr_number, stage, input_tokens, output_tokens,
|
||||
total_tokens, estimated_cost_usd, latency_ms, duration_ms,
|
||||
status, metadata, created_at
|
||||
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
""",
|
||||
(
|
||||
session_id,
|
||||
remote,
|
||||
org,
|
||||
repo,
|
||||
project_id,
|
||||
role,
|
||||
model,
|
||||
issue_number,
|
||||
pr_number,
|
||||
stage,
|
||||
input_tokens,
|
||||
output_tokens,
|
||||
total_tokens,
|
||||
estimated_cost_usd,
|
||||
latency_ms,
|
||||
duration_ms,
|
||||
status,
|
||||
meta_str,
|
||||
ts,
|
||||
),
|
||||
)
|
||||
return cursor.lastrowid
|
||||
|
||||
def query_usage_events(
|
||||
self,
|
||||
*,
|
||||
remote: str | None = None,
|
||||
org: str | None = None,
|
||||
repo: str | None = None,
|
||||
project_id: str | None = None,
|
||||
role: str | None = None,
|
||||
model: str | None = None,
|
||||
issue_number: int | None = None,
|
||||
pr_number: int | None = None,
|
||||
stage: str | None = None,
|
||||
session_id: str | None = None,
|
||||
limit: int = 500,
|
||||
offset: int = 0,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Query stored usage events matching filters (#651)."""
|
||||
conditions = []
|
||||
params = []
|
||||
if remote:
|
||||
conditions.append("remote = ?")
|
||||
params.append(remote)
|
||||
if org:
|
||||
conditions.append("org = ?")
|
||||
params.append(org)
|
||||
if repo:
|
||||
conditions.append("repo = ?")
|
||||
params.append(repo)
|
||||
if project_id:
|
||||
conditions.append("project_id = ?")
|
||||
params.append(project_id)
|
||||
if role:
|
||||
conditions.append("role = ?")
|
||||
params.append(role)
|
||||
if model:
|
||||
conditions.append("model = ?")
|
||||
params.append(model)
|
||||
if issue_number is not None:
|
||||
conditions.append("issue_number = ?")
|
||||
params.append(issue_number)
|
||||
if pr_number is not None:
|
||||
conditions.append("pr_number = ?")
|
||||
params.append(pr_number)
|
||||
if stage:
|
||||
conditions.append("stage = ?")
|
||||
params.append(stage)
|
||||
if session_id:
|
||||
conditions.append("session_id = ?")
|
||||
params.append(session_id)
|
||||
|
||||
where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
|
||||
sql = f"""
|
||||
SELECT * FROM usage_events
|
||||
{where_clause}
|
||||
ORDER BY usage_id ASC
|
||||
LIMIT ? OFFSET ?
|
||||
"""
|
||||
params.extend([limit, offset])
|
||||
|
||||
with self._tx(immediate=False) as conn:
|
||||
cursor = conn.execute(sql, params)
|
||||
rows = cursor.fetchall()
|
||||
return [dict(row) for row in rows]
|
||||
|
||||
# ── sessions ──────────────────────────────────────────────────────────
|
||||
|
||||
def upsert_session(
|
||||
|
||||
@@ -1,125 +0,0 @@
|
||||
# Model Usage, Token Cost, Latency, and Workflow Analytics (Phase 4)
|
||||
|
||||
- **Tracking Issue:** [#651](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/651)
|
||||
- **Parent Epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/651)
|
||||
- **Console Surface:** `/analytics`, `/api/v1/analytics`, `/api/v1/analytics/usage`
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The Web Console Analytics module provides durable, aggregate visibility into **model usage, token cost, latency percentiles, and workflow-stage performance** across projects, worker roles, AI models, issues, and PRs.
|
||||
|
||||
### Non-Goals
|
||||
- No mandatory client-side telemetry that leaks prompts or secret keys.
|
||||
- No third-party payment provider or billing integration.
|
||||
- No automatic model routing changes without controller policy (#647).
|
||||
|
||||
---
|
||||
|
||||
## 2. Event Schema (`usage_events`)
|
||||
|
||||
Usage metrics are stored in the control-plane database under table `usage_events`.
|
||||
|
||||
| Column | Type | Description |
|
||||
|---|---|---|
|
||||
| `usage_id` | `INTEGER` | Primary key (autoincrement) |
|
||||
| `session_id` | `TEXT` | Optional active session identifier |
|
||||
| `remote` | `TEXT` | Known Gitea instance (`dadeschools` or `prgs`) |
|
||||
| `org` | `TEXT` | Repository owner / organization |
|
||||
| `repo` | `TEXT` | Repository name |
|
||||
| `project_id` | `TEXT` | Optional project identifier |
|
||||
| `role` | `TEXT` | Active worker role (`author`, `reviewer`, `merger`, `reconciler`, `controller`) |
|
||||
| `model` | `TEXT` | LLM model identifier (e.g. `gemini-3.6-flash`, `claude-3-5-sonnet`) |
|
||||
| `issue_number` | `INTEGER` | Correlated Gitea issue number (optional) |
|
||||
| `pr_number` | `INTEGER` | Correlated Gitea PR number (optional) |
|
||||
| `stage` | `TEXT` | Workflow stage (`preflight`, `implementation`, `review`, `merge`, `reconciliation`) |
|
||||
| `input_tokens` | `INTEGER` | Input token count (optional / nullable) |
|
||||
| `output_tokens` | `INTEGER` | Output token count (optional / nullable) |
|
||||
| `total_tokens` | `INTEGER` | Total token count (optional / nullable) |
|
||||
| `estimated_cost_usd` | `REAL` | Estimated USD cost (optional / nullable) |
|
||||
| `latency_ms` | `INTEGER` | Request latency in milliseconds (optional / nullable) |
|
||||
| `duration_ms` | `INTEGER` | Stage execution duration in milliseconds (optional / nullable) |
|
||||
| `status` | `TEXT` | Outcome status (`success`, `failure`, `timeout`) |
|
||||
| `metadata` | `TEXT` | Redacted metadata or summary string |
|
||||
| `created_at` | `TEXT` | ISO 8601 UTC timestamp |
|
||||
|
||||
---
|
||||
|
||||
## 3. Handling of Missing Data ("Unknown" vs. Zero Fabrication)
|
||||
|
||||
To ensure operational metrics accurately reflect evidence:
|
||||
- **Untracked or missing metrics are displayed as `Unknown`**, never zero-fabricated.
|
||||
- If an event omits `estimated_cost_usd`, `latency_ms`, or token counts, the aggregator marks those fields as missing (`None`) rather than defaulting to `0` or `$0.00`.
|
||||
- Summary tables and KPI cards explicitly indicate when data is unmeasured or partially reported.
|
||||
|
||||
---
|
||||
|
||||
## 4. Redaction & Security Rules
|
||||
|
||||
Per `#633` security policy:
|
||||
- Free-text fields (`metadata`, `prompt_summary`, `session_id`) are run through `console_redaction.redact_text` before persistence and output serialization.
|
||||
- Secret tokens, keychain commands, authorization headers, passwords, and JWTs are stripped automatically.
|
||||
|
||||
---
|
||||
|
||||
## 5. Opt-in Instrumentation Guide
|
||||
|
||||
Applications, MCP servers, and background sessions can report usage metrics through either Python API or HTTP ingestion.
|
||||
|
||||
### Python Ingestion
|
||||
|
||||
```python
|
||||
from webui.analytics_loader import record_usage
|
||||
|
||||
record_usage(
|
||||
remote="dadeschools",
|
||||
org="Scaled-Tech-Consulting",
|
||||
repo="Gitea-Tools",
|
||||
role="author",
|
||||
model="gemini-3.6-flash",
|
||||
issue_number=651,
|
||||
stage="implementation",
|
||||
input_tokens=1420,
|
||||
output_tokens=380,
|
||||
total_tokens=1800,
|
||||
estimated_cost_usd=0.00045,
|
||||
latency_ms=320,
|
||||
duration_ms=4500,
|
||||
status="success",
|
||||
metadata={"note": "Implementation of analytics module"},
|
||||
)
|
||||
```
|
||||
|
||||
### HTTP Ingestion API
|
||||
|
||||
```http
|
||||
POST /api/v1/analytics/usage HTTP/1.1
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"remote": "dadeschools",
|
||||
"org": "Scaled-Tech-Consulting",
|
||||
"repo": "Gitea-Tools",
|
||||
"role": "author",
|
||||
"model": "gemini-3.6-flash",
|
||||
"issue_number": 651,
|
||||
"stage": "implementation",
|
||||
"input_tokens": 1420,
|
||||
"output_tokens": 380,
|
||||
"total_tokens": 1800,
|
||||
"estimated_cost_usd": 0.00045,
|
||||
"latency_ms": 320,
|
||||
"duration_ms": 4500,
|
||||
"status": "success",
|
||||
"metadata": "Analytics schema landed"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Querying Analytics API
|
||||
|
||||
```http
|
||||
GET /api/v1/analytics?role=author&stage=implementation HTTP/1.1
|
||||
```
|
||||
|
||||
Returns `AnalyticsSnapshot` JSON containing aggregations (`by_model`, `by_stage`, `by_role`, `by_work_item`, `by_project`) and latency percentiles (`p50`, `p90`, `p95`, `p99`).
|
||||
@@ -54,6 +54,7 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
|
||||
| `/` | Home / operator overview |
|
||||
| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`, `uptime_seconds`) |
|
||||
| `/api/v1/system/health` | Structured read-only system health (#634) |
|
||||
| `/system-health` | System-health dashboard — readiness, version/uptime, dependencies, MCP namespaces, stale-runtime parity (#639) |
|
||||
| `/queue` | Live PR and issue queue dashboard (#429) |
|
||||
| `/api/queue` | JSON queue export with pagination metadata |
|
||||
| `/projects` | Project registry list with status and onboarding progress (#427, #635) |
|
||||
@@ -258,6 +259,37 @@ Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`,
|
||||
surfaces are backed by #636). Mutating methods on stub routes still fail closed
|
||||
with `read-only-mvp`.
|
||||
|
||||
## System-health dashboard (#639)
|
||||
|
||||
`/system-health` renders the same snapshot the `/api/v1/system/health` API
|
||||
returns, so the page and the API can never disagree. Cards: overall readiness,
|
||||
stale-runtime parity, version and uptime, dependency probes, MCP namespaces,
|
||||
probe errors (only when present), and recovery pointers. `?deep=1` opts into
|
||||
the network probe exactly as the API does; the plain page load stays cheap.
|
||||
|
||||
Field authority and honesty rules:
|
||||
|
||||
* `ready` and `readiness_complete` are shown separately. A snapshot whose
|
||||
required probes never ran is not the same as one that ran them and passed,
|
||||
and the page never collapses the two into an unproven green.
|
||||
* A probe that did not run appears under **Not probed**, never as healthy.
|
||||
* `stale_runtime.mutation_safe` is displayed verbatim from the API. When the
|
||||
runtime is stale, or when parity is indeterminate, the page warns and does
|
||||
not claim mutation safety.
|
||||
* MCP namespaces are reported `unproven`: the web process runs outside the
|
||||
IDE-managed MCP client and cannot prove that path (#543).
|
||||
|
||||
Redaction is split by field kind. Free text — probe details, readiness and
|
||||
parity reasons, probe errors — passes through `system_health.redact`.
|
||||
Structured fields — commit SHAs, probe names, statuses, timestamps — are
|
||||
HTML-escaped only, because `redact`'s opaque-token rule matches any run of 32
|
||||
or more characters and would otherwise blank every 40-character git SHA, which
|
||||
is precisely the evidence the parity view exists to show.
|
||||
|
||||
The dashboard is read-only: no restart, reload, or process-kill control. Those
|
||||
arrive in Phase 2 (#642). Recovery guidance points at the sanctioned client
|
||||
reconnect / operator restart path — never a manual daemon kill (#630).
|
||||
|
||||
## Deployment boundary (#435)
|
||||
|
||||
MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused**
|
||||
|
||||
@@ -36,7 +36,7 @@ class ControlPlaneDBTest(unittest.TestCase):
|
||||
rows = dict(conn.execute("SELECT key, value FROM schema_meta").fetchall())
|
||||
finally:
|
||||
conn.close()
|
||||
self.assertEqual(rows["schema_version"], "5")
|
||||
self.assertEqual(rows["schema_version"], "4")
|
||||
self.assertIn("DB coordinates", rows["architecture"])
|
||||
self.assertIn("bridge", rows["architecture"].lower())
|
||||
|
||||
|
||||
@@ -1,196 +0,0 @@
|
||||
"""Unit and integration tests for Model Usage & Performance Analytics (#651)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import tempfile
|
||||
import unittest
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
import control_plane_db
|
||||
from webui.analytics_loader import (
|
||||
ANALYTICS_SCHEMA_VERSION,
|
||||
compute_percentile,
|
||||
load_analytics,
|
||||
record_usage,
|
||||
)
|
||||
from webui.app import create_app
|
||||
from webui import console_redaction
|
||||
|
||||
|
||||
class AnalyticsLoaderTest(unittest.TestCase):
|
||||
|
||||
def setUp(self) -> None:
|
||||
self.temp_dir = tempfile.TemporaryDirectory()
|
||||
self.db_path = os.path.join(self.temp_dir.name, "test_control_plane.sqlite3")
|
||||
os.environ["GITEA_CONTROL_PLANE_DB"] = self.db_path
|
||||
self.db = control_plane_db.ControlPlaneDB(db_path=self.db_path)
|
||||
|
||||
def tearDown(self) -> None:
|
||||
self.temp_dir.cleanup()
|
||||
|
||||
def test_compute_percentile(self) -> None:
|
||||
self.assertIsNone(compute_percentile([], 50.0))
|
||||
self.assertEqual(compute_percentile([100], 50.0), 100.0)
|
||||
|
||||
# 2 elements: [100, 200]
|
||||
self.assertEqual(compute_percentile([100, 200], 50.0), 150.0)
|
||||
|
||||
# 100 elements: 1..100
|
||||
vals = list(range(1, 101))
|
||||
self.assertEqual(compute_percentile(vals, 50.0), 50.5)
|
||||
self.assertAlmostEqual(compute_percentile(vals, 90.0), 90.1)
|
||||
|
||||
def test_record_and_aggregate_usage(self) -> None:
|
||||
# Record event 1 (complete data)
|
||||
u1 = record_usage(
|
||||
db_path=self.db_path,
|
||||
remote="dadeschools",
|
||||
org="Scaled-Tech-Consulting",
|
||||
repo="Gitea-Tools",
|
||||
role="author",
|
||||
model="gemini-3.6-flash",
|
||||
issue_number=651,
|
||||
stage="implementation",
|
||||
input_tokens=1000,
|
||||
output_tokens=500,
|
||||
estimated_cost_usd=0.0015,
|
||||
latency_ms=200,
|
||||
duration_ms=3000,
|
||||
metadata={"secret_key": "secret123", "note": "token=secret123"},
|
||||
)
|
||||
self.assertGreater(u1, 0)
|
||||
|
||||
# Record event 2 (missing tokens and cost -> unknown)
|
||||
u2 = record_usage(
|
||||
db_path=self.db_path,
|
||||
remote="dadeschools",
|
||||
org="Scaled-Tech-Consulting",
|
||||
repo="Gitea-Tools",
|
||||
role="reviewer",
|
||||
model="claude-3-5-sonnet",
|
||||
pr_number=846,
|
||||
stage="review",
|
||||
latency_ms=500,
|
||||
duration_ms=6000,
|
||||
)
|
||||
self.assertGreater(u2, u1)
|
||||
|
||||
snapshot = load_analytics(
|
||||
db_path=self.db_path,
|
||||
remote="dadeschools",
|
||||
org="Scaled-Tech-Consulting",
|
||||
repo="Gitea-Tools",
|
||||
)
|
||||
|
||||
self.assertTrue(snapshot.ok)
|
||||
self.assertEqual(snapshot.schema_version, ANALYTICS_SCHEMA_VERSION)
|
||||
self.assertEqual(snapshot.total_events, 2)
|
||||
|
||||
# Verify overall summary
|
||||
summary = snapshot.overall_summary
|
||||
self.assertEqual(summary.total_events, 2)
|
||||
self.assertEqual(summary.events_with_tokens, 1)
|
||||
self.assertEqual(summary.total_tokens, 1500)
|
||||
self.assertEqual(summary.events_with_cost, 1)
|
||||
self.assertEqual(summary.estimated_cost_usd, 0.0015)
|
||||
self.assertEqual(summary.events_with_latency, 2)
|
||||
self.assertEqual(summary.latency_p50_ms, 350.0)
|
||||
|
||||
# Verify missing data handling (AC 3: not zero-fabricated)
|
||||
reviewer_model = snapshot.by_model.get("claude-3-5-sonnet")
|
||||
self.assertIsNotNone(reviewer_model)
|
||||
self.assertEqual(reviewer_model.total_events, 1)
|
||||
self.assertEqual(reviewer_model.events_with_tokens, 0)
|
||||
self.assertIsNone(reviewer_model.total_tokens)
|
||||
self.assertEqual(reviewer_model.display_tokens, "Unknown")
|
||||
self.assertEqual(reviewer_model.events_with_cost, 0)
|
||||
self.assertIsNone(reviewer_model.estimated_cost_usd)
|
||||
self.assertEqual(reviewer_model.display_cost, "Unknown")
|
||||
|
||||
# Verify redaction (AC 4)
|
||||
e1 = [e for e in snapshot.events if e.usage_id == u1][0]
|
||||
self.assertIsNotNone(e1.metadata)
|
||||
self.assertNotIn("secret123", e1.metadata)
|
||||
self.assertIn("[REDACTED]", e1.metadata)
|
||||
|
||||
def test_missing_db_fail_soft(self) -> None:
|
||||
invalid_path = "/nonexistent_path_dir/db.sqlite3"
|
||||
snapshot = load_analytics(db_path=invalid_path)
|
||||
self.assertFalse(snapshot.ok)
|
||||
self.assertIn("control_plane_db_unavailable", snapshot.reason)
|
||||
self.assertEqual(snapshot.overall_summary.display_tokens, "Unknown")
|
||||
|
||||
|
||||
class AnalyticsWebUITest(unittest.TestCase):
|
||||
|
||||
def setUp(self) -> None:
|
||||
self.temp_dir = tempfile.TemporaryDirectory()
|
||||
self.db_path = os.path.join(self.temp_dir.name, "test_webui.sqlite3")
|
||||
os.environ["GITEA_CONTROL_PLANE_DB"] = self.db_path
|
||||
self.app = create_app()
|
||||
self.client = TestClient(self.app)
|
||||
|
||||
record_usage(
|
||||
db_path=self.db_path,
|
||||
remote="dadeschools",
|
||||
org="Scaled-Tech-Consulting",
|
||||
repo="Gitea-Tools",
|
||||
role="author",
|
||||
model="gemini-3.6-flash",
|
||||
issue_number=651,
|
||||
stage="implementation",
|
||||
input_tokens=2000,
|
||||
output_tokens=1000,
|
||||
estimated_cost_usd=0.003,
|
||||
latency_ms=150,
|
||||
duration_ms=2500,
|
||||
)
|
||||
|
||||
def tearDown(self) -> None:
|
||||
self.temp_dir.cleanup()
|
||||
|
||||
def test_analytics_html_route(self) -> None:
|
||||
response = self.client.get("/analytics")
|
||||
self.assertEqual(response.status_code, 200)
|
||||
self.assertIn("Model Usage & Performance Analytics", response.text)
|
||||
self.assertIn("gemini-3.6-flash", response.text)
|
||||
self.assertIn("3,000", response.text)
|
||||
|
||||
def test_analytics_api_route(self) -> None:
|
||||
response = self.client.get("/api/v1/analytics")
|
||||
self.assertEqual(response.status_code, 200)
|
||||
data = response.json()
|
||||
self.assertTrue(data["ok"])
|
||||
self.assertEqual(data["total_events"], 1)
|
||||
self.assertIn("gemini-3.6-flash", data["by_model"])
|
||||
|
||||
def test_analytics_ingest_endpoint(self) -> None:
|
||||
payload = {
|
||||
"remote": "dadeschools",
|
||||
"org": "Scaled-Tech-Consulting",
|
||||
"repo": "Gitea-Tools",
|
||||
"role": "reviewer",
|
||||
"model": "claude-3-5-sonnet",
|
||||
"pr_number": 846,
|
||||
"stage": "review",
|
||||
"input_tokens": 500,
|
||||
"output_tokens": 100,
|
||||
"latency_ms": 400,
|
||||
"metadata": "Review note token=secret456",
|
||||
}
|
||||
response = self.client.post("/api/v1/analytics/usage", json=payload)
|
||||
self.assertEqual(response.status_code, 201)
|
||||
res_json = response.json()
|
||||
self.assertTrue(res_json["ok"])
|
||||
self.assertGreater(res_json["usage_id"], 0)
|
||||
|
||||
# Check that it appears in GET /api/v1/analytics
|
||||
res2 = self.client.get("/api/v1/analytics")
|
||||
self.assertEqual(res2.status_code, 200)
|
||||
data2 = res2.json()
|
||||
self.assertEqual(data2["total_events"], 2)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,345 @@
|
||||
"""Tests for the system-health dashboard view (#639).
|
||||
|
||||
Covers the acceptance criteria directly: the page renders the health DTO
|
||||
fields (AC1), degraded dependencies are visible (AC2), stale runtime is warned
|
||||
prominently and never rendered as mutation-safe (AC3), healthy and degraded
|
||||
fixtures both render (AC4), and the shell carries a nav entry (AC5).
|
||||
"""
|
||||
import sys
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
||||
|
||||
from starlette.testclient import TestClient
|
||||
|
||||
from webui.app import create_app
|
||||
from webui.deployment_boundary import scan_text_for_client_secrets
|
||||
from webui.layout import render_page
|
||||
from webui.nav import iter_nav_items
|
||||
from webui.system_health import (
|
||||
STATUS_DEGRADED,
|
||||
STATUS_DOWN,
|
||||
STATUS_OK,
|
||||
STATUS_SKIPPED,
|
||||
STATUS_UNPROVEN,
|
||||
DependencyProbe,
|
||||
StaleRuntime,
|
||||
SystemHealthSnapshot,
|
||||
VersionInfo,
|
||||
)
|
||||
from webui.system_health_views import render_system_health_page
|
||||
|
||||
DASHBOARD_PATH = "/system-health"
|
||||
|
||||
|
||||
def _version(*, known: bool = True) -> VersionInfo:
|
||||
return VersionInfo(
|
||||
git_sha="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd" if known else None,
|
||||
git_describe="v0.4.1-12-g1c455b6" if known else None,
|
||||
control_plane_schema_version=4 if known else None,
|
||||
python_version="3.13.1",
|
||||
known=known,
|
||||
)
|
||||
|
||||
|
||||
def _parity(*, stale: bool = False, determinable: bool = True) -> StaleRuntime:
|
||||
if stale:
|
||||
return StaleRuntime(
|
||||
daemon_head="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
checkout_head="bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
|
||||
remote_head="cccccccccccccccccccccccccccccccccccccccc",
|
||||
stale=True,
|
||||
determinable=True,
|
||||
mutation_safe=False,
|
||||
reasons=("runtime, checkout, and remote commits disagree",),
|
||||
)
|
||||
if not determinable:
|
||||
return StaleRuntime(
|
||||
daemon_head=None,
|
||||
checkout_head=None,
|
||||
remote_head=None,
|
||||
stale=False,
|
||||
determinable=False,
|
||||
mutation_safe=False,
|
||||
reasons=("local checkout HEAD could not be read",),
|
||||
)
|
||||
return StaleRuntime(
|
||||
daemon_head="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd",
|
||||
checkout_head="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd",
|
||||
remote_head="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd",
|
||||
stale=False,
|
||||
determinable=True,
|
||||
mutation_safe=True,
|
||||
reasons=(),
|
||||
)
|
||||
|
||||
|
||||
def _snapshot(
|
||||
*,
|
||||
status: str = STATUS_OK,
|
||||
ready: bool = True,
|
||||
readiness_complete: bool = True,
|
||||
readiness_reasons: tuple[str, ...] = (),
|
||||
dependencies: tuple[DependencyProbe, ...] | None = None,
|
||||
parity: StaleRuntime | None = None,
|
||||
namespaces: tuple[dict, ...] = (),
|
||||
probe_errors: tuple[str, ...] = (),
|
||||
version_known: bool = True,
|
||||
) -> SystemHealthSnapshot:
|
||||
if dependencies is None:
|
||||
dependencies = (
|
||||
DependencyProbe(
|
||||
name="control_plane_db",
|
||||
kind="sqlite",
|
||||
status=STATUS_OK,
|
||||
detail="schema version 4",
|
||||
required=True,
|
||||
latency_ms=1.25,
|
||||
metadata={"schema_version": 4},
|
||||
),
|
||||
)
|
||||
return SystemHealthSnapshot(
|
||||
status=status,
|
||||
ready=ready,
|
||||
readiness_complete=readiness_complete,
|
||||
readiness_reasons=readiness_reasons,
|
||||
service="mcp-control-plane-webui",
|
||||
mode="read-only",
|
||||
version=_version(known=version_known),
|
||||
started_at="2026-07-23T19:50:47+00:00",
|
||||
uptime_seconds=3661.5,
|
||||
timestamp="2026-07-23T20:51:48+00:00",
|
||||
deep_probes_requested=False,
|
||||
dependencies=dependencies,
|
||||
mcp_namespaces=namespaces,
|
||||
stale_runtime=parity if parity is not None else _parity(),
|
||||
probe_errors=probe_errors,
|
||||
)
|
||||
|
||||
|
||||
class TestHealthyRender(unittest.TestCase):
|
||||
"""AC1 / AC4 — every health DTO field reaches the page."""
|
||||
|
||||
def setUp(self):
|
||||
self.html = render_system_health_page(_snapshot())
|
||||
|
||||
def test_readiness_fields_render(self):
|
||||
self.assertIn("System health", self.html)
|
||||
self.assertIn("Ready", self.html)
|
||||
self.assertIn("mcp-control-plane-webui", self.html)
|
||||
self.assertIn("read-only", self.html)
|
||||
self.assertIn("2026-07-23T20:51:48+00:00", self.html)
|
||||
|
||||
def test_version_and_uptime_render(self):
|
||||
self.assertIn("1c455b6ec0f9cb761fe6248de68c17e061fb5ecd", self.html)
|
||||
self.assertIn("v0.4.1-12-g1c455b6", self.html)
|
||||
self.assertIn("3.13.1", self.html)
|
||||
self.assertIn("3661.500s", self.html)
|
||||
self.assertIn("1.02h", self.html)
|
||||
|
||||
def test_dependency_row_renders_with_latency(self):
|
||||
self.assertIn("control_plane_db", self.html)
|
||||
self.assertIn("sqlite", self.html)
|
||||
self.assertIn("schema version 4", self.html)
|
||||
self.assertIn("1.2 ms", self.html)
|
||||
|
||||
def test_healthy_page_shows_no_stale_warning(self):
|
||||
self.assertNotIn("Stale runtime:", self.html)
|
||||
self.assertNotIn("Staleness", self.html)
|
||||
|
||||
def test_unknown_version_is_labelled_not_faked(self):
|
||||
html = render_system_health_page(_snapshot(version_known=False))
|
||||
self.assertIn("unknown", html)
|
||||
self.assertIn("unresolved", html)
|
||||
|
||||
|
||||
class TestDegradedRender(unittest.TestCase):
|
||||
"""AC2 — a degraded or unrun dependency is visible, not swallowed."""
|
||||
|
||||
def setUp(self):
|
||||
self.deps = (
|
||||
DependencyProbe(
|
||||
name="control_plane_db",
|
||||
kind="sqlite",
|
||||
status=STATUS_OK,
|
||||
detail="schema version 4",
|
||||
required=True,
|
||||
latency_ms=0.9,
|
||||
),
|
||||
DependencyProbe(
|
||||
name="repository",
|
||||
kind="git",
|
||||
status=STATUS_DOWN,
|
||||
detail="repository root is not a git checkout",
|
||||
required=True,
|
||||
latency_ms=4.0,
|
||||
),
|
||||
DependencyProbe(
|
||||
name="gitea",
|
||||
kind="http",
|
||||
status=STATUS_SKIPPED,
|
||||
detail="deep probe not requested",
|
||||
required=False,
|
||||
),
|
||||
)
|
||||
self.html = render_system_health_page(
|
||||
_snapshot(
|
||||
status=STATUS_DEGRADED,
|
||||
ready=False,
|
||||
readiness_complete=False,
|
||||
readiness_reasons=("required dependency 'repository' is down",),
|
||||
dependencies=self.deps,
|
||||
)
|
||||
)
|
||||
|
||||
def test_degraded_banner_names_the_dependency(self):
|
||||
self.assertIn("Degraded dependencies:", self.html)
|
||||
self.assertIn("repository", self.html)
|
||||
|
||||
def test_not_run_probe_is_reported_separately(self):
|
||||
self.assertIn("Not probed:", self.html)
|
||||
self.assertIn("gitea", self.html)
|
||||
self.assertIn("not counted", self.html)
|
||||
|
||||
def test_not_ready_headline_and_reason(self):
|
||||
self.assertIn("Not ready", self.html)
|
||||
self.assertIn("required dependency 'repository' is down", self.html)
|
||||
|
||||
def test_degraded_status_badge_present(self):
|
||||
self.assertIn("badge-health-degraded", self.html)
|
||||
self.assertIn("badge-health-down", self.html)
|
||||
|
||||
def test_ready_but_incomplete_is_not_shown_as_plain_ready(self):
|
||||
html = render_system_health_page(
|
||||
_snapshot(ready=True, readiness_complete=False)
|
||||
)
|
||||
self.assertIn("Ready (incomplete evidence)", html)
|
||||
|
||||
|
||||
class TestStaleRuntimeWarning(unittest.TestCase):
|
||||
"""AC3 — staleness is prominent and never claims mutation safety."""
|
||||
|
||||
def test_stale_runtime_warns_and_denies_mutation_safety(self):
|
||||
html = render_system_health_page(_snapshot(parity=_parity(stale=True)))
|
||||
self.assertIn("Stale runtime:", html)
|
||||
self.assertIn("do not treat this runtime as mutation-safe", html)
|
||||
self.assertIn("<tr><th>Mutation safe</th><td>False</td></tr>", html)
|
||||
|
||||
def test_indeterminate_parity_is_not_reported_safe(self):
|
||||
html = render_system_health_page(
|
||||
_snapshot(parity=_parity(determinable=False))
|
||||
)
|
||||
self.assertIn("Staleness", html)
|
||||
self.assertIn("<tr><th>Mutation safe</th><td>False</td></tr>", html)
|
||||
self.assertIn("<tr><th>Determinable</th><td>False</td></tr>", html)
|
||||
|
||||
def test_healthy_parity_reports_mutation_safe_true(self):
|
||||
html = render_system_health_page(_snapshot())
|
||||
self.assertIn("<tr><th>Mutation safe</th><td>True</td></tr>", html)
|
||||
|
||||
|
||||
class TestNamespacesAndErrors(unittest.TestCase):
|
||||
def test_unproven_namespace_rows_render(self):
|
||||
html = render_system_health_page(
|
||||
_snapshot(
|
||||
namespaces=(
|
||||
{
|
||||
"namespace": "gitea-author",
|
||||
"required_tool": "gitea_lock_issue",
|
||||
"status": STATUS_UNPROVEN,
|
||||
"ide_namespace_proven": False,
|
||||
"reason": "the web console cannot invoke the IDE-managed MCP client",
|
||||
},
|
||||
)
|
||||
)
|
||||
)
|
||||
self.assertIn("gitea-author", html)
|
||||
self.assertIn("gitea_lock_issue", html)
|
||||
self.assertIn("badge-health-unproven", html)
|
||||
|
||||
def test_no_namespaces_degrades_gracefully(self):
|
||||
html = render_system_health_page(_snapshot(namespaces=()))
|
||||
self.assertIn("No MCP namespaces are declared.", html)
|
||||
|
||||
def test_probe_errors_render_when_present(self):
|
||||
html = render_system_health_page(
|
||||
_snapshot(probe_errors=("probe raised: disk offline",))
|
||||
)
|
||||
self.assertIn("Probe errors", html)
|
||||
self.assertIn("disk offline", html)
|
||||
|
||||
def test_probe_error_card_absent_when_clean(self):
|
||||
self.assertNotIn("Probe errors", render_system_health_page(_snapshot()))
|
||||
|
||||
|
||||
class TestReadOnlyAndRedaction(unittest.TestCase):
|
||||
def test_no_restart_or_kill_controls(self):
|
||||
html = render_system_health_page(_snapshot())
|
||||
self.assertNotIn("<button", html)
|
||||
self.assertNotIn("<form", html)
|
||||
self.assertNotIn("pkill", html)
|
||||
self.assertIn("read-only", html)
|
||||
|
||||
def test_recovery_points_at_sanctioned_path(self):
|
||||
html = render_system_health_page(_snapshot())
|
||||
self.assertIn("Reconnect the MCP client", html)
|
||||
self.assertIn("Never kill the daemon process manually", html)
|
||||
|
||||
def test_secret_shaped_detail_is_redacted(self):
|
||||
leaky = DependencyProbe(
|
||||
name="gitea",
|
||||
kind="http",
|
||||
status=STATUS_DOWN,
|
||||
detail="auth failed for token=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
|
||||
required=False,
|
||||
latency_ms=12.0,
|
||||
)
|
||||
html = render_system_health_page(_snapshot(dependencies=(leaky,)))
|
||||
self.assertNotIn("ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", html)
|
||||
|
||||
def test_html_in_detail_is_escaped(self):
|
||||
hostile = DependencyProbe(
|
||||
name="repository",
|
||||
kind="git",
|
||||
status=STATUS_DOWN,
|
||||
detail="<script>alert(1)</script>",
|
||||
required=True,
|
||||
)
|
||||
html = render_system_health_page(_snapshot(dependencies=(hostile,)))
|
||||
self.assertNotIn("<script>", html)
|
||||
self.assertIn("<script>", html)
|
||||
|
||||
|
||||
class TestNavAndRoute(unittest.TestCase):
|
||||
"""AC5 — the shell links the dashboard, and the route serves it."""
|
||||
|
||||
def setUp(self):
|
||||
self.client = TestClient(create_app())
|
||||
|
||||
def test_nav_contains_system_health(self):
|
||||
self.assertIn(
|
||||
(DASHBOARD_PATH, "System health"),
|
||||
[(item.href, item.label) for item in iter_nav_items()],
|
||||
)
|
||||
|
||||
def test_rendered_shell_links_dashboard(self):
|
||||
page = render_page(title="Home", body_html="<p>x</p>")
|
||||
self.assertIn(f'href="{DASHBOARD_PATH}"', page)
|
||||
|
||||
def test_route_renders_dashboard(self):
|
||||
response = self.client.get(DASHBOARD_PATH)
|
||||
self.assertEqual(response.status_code, 200)
|
||||
self.assertIn("System health", response.text)
|
||||
self.assertIn("Stale-runtime parity", response.text)
|
||||
|
||||
def test_route_is_read_only(self):
|
||||
self.assertEqual(self.client.post(DASHBOARD_PATH).status_code, 405)
|
||||
|
||||
def test_live_page_leaks_no_client_secret(self):
|
||||
findings = scan_text_for_client_secrets(self.client.get(DASHBOARD_PATH).text)
|
||||
self.assertEqual(findings, [])
|
||||
|
||||
|
||||
if __name__ == "__main__": # pragma: no cover
|
||||
unittest.main()
|
||||
@@ -1,428 +0,0 @@
|
||||
"""Model usage, token cost, latency, and workflow-performance analytics (#651, Phase 4).
|
||||
|
||||
Ingests session instrumentation metrics, aggregates usage/cost/latency percentiles
|
||||
by project, role, model, issue/PR, and stage, enforcing secret redaction and
|
||||
explicitly rendering missing metrics as "Unknown" without zero-fabrication.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
from dataclasses import asdict, dataclass
|
||||
from typing import Any, Sequence
|
||||
|
||||
import control_plane_db
|
||||
from webui import console_redaction
|
||||
|
||||
ANALYTICS_SCHEMA_VERSION = 1
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class UsageEvent:
|
||||
usage_id: int
|
||||
session_id: str | None
|
||||
remote: str
|
||||
org: str
|
||||
repo: str
|
||||
project_id: str | None
|
||||
role: str
|
||||
model: str
|
||||
issue_number: int | None
|
||||
pr_number: int | None
|
||||
stage: str
|
||||
input_tokens: int | None
|
||||
output_tokens: int | None
|
||||
total_tokens: int | None
|
||||
estimated_cost_usd: float | None
|
||||
latency_ms: int | None
|
||||
duration_ms: int | None
|
||||
status: str
|
||||
metadata: str | None
|
||||
created_at: str
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
d = asdict(self)
|
||||
if d["metadata"]:
|
||||
d["metadata"] = console_redaction.redact_text(d["metadata"])
|
||||
return d
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class GroupMetrics:
|
||||
name: str
|
||||
total_events: int
|
||||
events_with_tokens: int
|
||||
input_tokens: int | None
|
||||
output_tokens: int | None
|
||||
total_tokens: int | None
|
||||
events_with_cost: int
|
||||
estimated_cost_usd: float | None
|
||||
events_with_latency: int
|
||||
latency_p50_ms: float | None
|
||||
latency_p90_ms: float | None
|
||||
latency_p95_ms: float | None
|
||||
latency_p99_ms: float | None
|
||||
latency_avg_ms: float | None
|
||||
events_with_duration: int
|
||||
duration_avg_ms: float | None
|
||||
display_tokens: str
|
||||
display_cost: str
|
||||
display_latency_p50: str
|
||||
display_latency_p90: str
|
||||
display_duration_avg: str
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return asdict(self)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class AnalyticsSnapshot:
|
||||
ok: bool
|
||||
reason: str
|
||||
schema_version: int
|
||||
remote: str
|
||||
org: str
|
||||
repo: str
|
||||
total_events: int
|
||||
overall_summary: GroupMetrics
|
||||
by_project: dict[str, GroupMetrics]
|
||||
by_role: dict[str, GroupMetrics]
|
||||
by_model: dict[str, GroupMetrics]
|
||||
by_work_item: dict[str, GroupMetrics]
|
||||
by_stage: dict[str, GroupMetrics]
|
||||
events: tuple[UsageEvent, ...]
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"ok": self.ok,
|
||||
"reason": self.reason,
|
||||
"schema_version": self.schema_version,
|
||||
"remote": self.remote,
|
||||
"org": self.org,
|
||||
"repo": self.repo,
|
||||
"total_events": self.total_events,
|
||||
"overall_summary": self.overall_summary.to_dict(),
|
||||
"by_project": {k: v.to_dict() for k, v in self.by_project.items()},
|
||||
"by_role": {k: v.to_dict() for k, v in self.by_role.items()},
|
||||
"by_model": {k: v.to_dict() for k, v in self.by_model.items()},
|
||||
"by_work_item": {k: v.to_dict() for k, v in self.by_work_item.items()},
|
||||
"by_stage": {k: v.to_dict() for k, v in self.by_stage.items()},
|
||||
"events": [e.to_dict() for e in self.events],
|
||||
}
|
||||
|
||||
|
||||
def compute_percentile(values: Sequence[float | int], percentile: float) -> float | None:
|
||||
if not values:
|
||||
return None
|
||||
sorted_vals = sorted(values)
|
||||
n = len(sorted_vals)
|
||||
if n == 1:
|
||||
return float(sorted_vals[0])
|
||||
k = (n - 1) * (percentile / 100.0)
|
||||
f = math.floor(k)
|
||||
c = math.ceil(k)
|
||||
if f == c:
|
||||
return float(sorted_vals[int(f)])
|
||||
d0 = sorted_vals[int(f)] * (c - k)
|
||||
d1 = sorted_vals[int(c)] * (k - f)
|
||||
return float(d0 + d1)
|
||||
|
||||
|
||||
def aggregate_events(group_name: str, events: Sequence[UsageEvent]) -> GroupMetrics:
|
||||
total_events = len(events)
|
||||
if total_events == 0:
|
||||
return GroupMetrics(
|
||||
name=group_name,
|
||||
total_events=0,
|
||||
events_with_tokens=0,
|
||||
input_tokens=None,
|
||||
output_tokens=None,
|
||||
total_tokens=None,
|
||||
events_with_cost=0,
|
||||
estimated_cost_usd=None,
|
||||
events_with_latency=0,
|
||||
latency_p50_ms=None,
|
||||
latency_p90_ms=None,
|
||||
latency_p95_ms=None,
|
||||
latency_p99_ms=None,
|
||||
latency_avg_ms=None,
|
||||
events_with_duration=0,
|
||||
duration_avg_ms=None,
|
||||
display_tokens="Unknown",
|
||||
display_cost="Unknown",
|
||||
display_latency_p50="Unknown",
|
||||
display_latency_p90="Unknown",
|
||||
display_duration_avg="Unknown",
|
||||
)
|
||||
|
||||
token_events = [
|
||||
e for e in events
|
||||
if e.total_tokens is not None or e.input_tokens is not None or e.output_tokens is not None
|
||||
]
|
||||
events_with_tokens = len(token_events)
|
||||
if events_with_tokens > 0:
|
||||
input_tokens = sum(e.input_tokens or 0 for e in token_events)
|
||||
output_tokens = sum(e.output_tokens or 0 for e in token_events)
|
||||
total_tokens = sum(
|
||||
e.total_tokens if e.total_tokens is not None else ((e.input_tokens or 0) + (e.output_tokens or 0))
|
||||
for e in token_events
|
||||
)
|
||||
display_tokens = f"{total_tokens:,}"
|
||||
else:
|
||||
input_tokens = None
|
||||
output_tokens = None
|
||||
total_tokens = None
|
||||
display_tokens = "Unknown"
|
||||
|
||||
cost_events = [e for e in events if e.estimated_cost_usd is not None]
|
||||
events_with_cost = len(cost_events)
|
||||
if events_with_cost > 0:
|
||||
estimated_cost_usd = round(sum(e.estimated_cost_usd for e in cost_events), 6)
|
||||
display_cost = f"${estimated_cost_usd:.4f}"
|
||||
else:
|
||||
estimated_cost_usd = None
|
||||
display_cost = "Unknown"
|
||||
|
||||
latency_vals = [e.latency_ms for e in events if e.latency_ms is not None]
|
||||
events_with_latency = len(latency_vals)
|
||||
if events_with_latency > 0:
|
||||
latency_p50_ms = compute_percentile(latency_vals, 50.0)
|
||||
latency_p90_ms = compute_percentile(latency_vals, 90.0)
|
||||
latency_p95_ms = compute_percentile(latency_vals, 95.0)
|
||||
latency_p99_ms = compute_percentile(latency_vals, 99.0)
|
||||
latency_avg_ms = round(sum(latency_vals) / events_with_latency, 2)
|
||||
display_latency_p50 = f"{round(latency_p50_ms, 1)} ms" if latency_p50_ms is not None else "Unknown"
|
||||
display_latency_p90 = f"{round(latency_p90_ms, 1)} ms" if latency_p90_ms is not None else "Unknown"
|
||||
else:
|
||||
latency_p50_ms = None
|
||||
latency_p90_ms = None
|
||||
latency_p95_ms = None
|
||||
latency_p99_ms = None
|
||||
latency_avg_ms = None
|
||||
display_latency_p50 = "Unknown"
|
||||
display_latency_p90 = "Unknown"
|
||||
|
||||
duration_vals = [e.duration_ms for e in events if e.duration_ms is not None]
|
||||
events_with_duration = len(duration_vals)
|
||||
if events_with_duration > 0:
|
||||
duration_avg_ms = round(sum(duration_vals) / events_with_duration, 2)
|
||||
display_duration_avg = f"{round(duration_avg_ms / 1000.0, 2)} s" if duration_avg_ms >= 1000 else f"{round(duration_avg_ms, 1)} ms"
|
||||
else:
|
||||
duration_avg_ms = None
|
||||
display_duration_avg = "Unknown"
|
||||
|
||||
return GroupMetrics(
|
||||
name=group_name,
|
||||
total_events=total_events,
|
||||
events_with_tokens=events_with_tokens,
|
||||
input_tokens=input_tokens,
|
||||
output_tokens=output_tokens,
|
||||
total_tokens=total_tokens,
|
||||
events_with_cost=events_with_cost,
|
||||
estimated_cost_usd=estimated_cost_usd,
|
||||
events_with_latency=events_with_latency,
|
||||
latency_p50_ms=latency_p50_ms,
|
||||
latency_p90_ms=latency_p90_ms,
|
||||
latency_p95_ms=latency_p95_ms,
|
||||
latency_p99_ms=latency_p99_ms,
|
||||
latency_avg_ms=latency_avg_ms,
|
||||
events_with_duration=events_with_duration,
|
||||
duration_avg_ms=duration_avg_ms,
|
||||
display_tokens=display_tokens,
|
||||
display_cost=display_cost,
|
||||
display_latency_p50=display_latency_p50,
|
||||
display_latency_p90=display_latency_p90,
|
||||
display_duration_avg=display_duration_avg,
|
||||
)
|
||||
|
||||
|
||||
def record_usage(
|
||||
*,
|
||||
db_path: str | None = None,
|
||||
session_id: str | None = None,
|
||||
remote: str = "dadeschools",
|
||||
org: str = "",
|
||||
repo: str = "",
|
||||
project_id: str | None = None,
|
||||
role: str = "unknown",
|
||||
model: str = "unknown",
|
||||
issue_number: int | None = None,
|
||||
pr_number: int | None = None,
|
||||
stage: str = "unknown",
|
||||
input_tokens: int | None = None,
|
||||
output_tokens: int | None = None,
|
||||
total_tokens: int | None = None,
|
||||
estimated_cost_usd: float | None = None,
|
||||
latency_ms: int | None = None,
|
||||
duration_ms: int | None = None,
|
||||
status: str = "success",
|
||||
metadata: str | dict[str, Any] | None = None,
|
||||
created_at: str | None = None,
|
||||
) -> int:
|
||||
"""Ingest/record a single usage event with optional metrics."""
|
||||
db = control_plane_db.ControlPlaneDB(db_path=db_path)
|
||||
return db.record_usage_event(
|
||||
session_id=session_id,
|
||||
remote=remote,
|
||||
org=org,
|
||||
repo=repo,
|
||||
project_id=project_id,
|
||||
role=role,
|
||||
model=model,
|
||||
issue_number=issue_number,
|
||||
pr_number=pr_number,
|
||||
stage=stage,
|
||||
input_tokens=input_tokens,
|
||||
output_tokens=output_tokens,
|
||||
total_tokens=total_tokens,
|
||||
estimated_cost_usd=estimated_cost_usd,
|
||||
latency_ms=latency_ms,
|
||||
duration_ms=duration_ms,
|
||||
status=status,
|
||||
metadata=metadata,
|
||||
created_at=created_at,
|
||||
)
|
||||
|
||||
|
||||
def load_analytics(
|
||||
*,
|
||||
db_path: str | None = None,
|
||||
remote: str | None = None,
|
||||
org: str | None = None,
|
||||
repo: str | None = None,
|
||||
project_id: str | None = None,
|
||||
role: str | None = None,
|
||||
model: str | None = None,
|
||||
stage: str | None = None,
|
||||
issue_number: int | None = None,
|
||||
pr_number: int | None = None,
|
||||
limit: int = 500,
|
||||
) -> AnalyticsSnapshot:
|
||||
"""Load analytics snapshot aggregated by project, role, model, issue/PR, and stage."""
|
||||
remote_filter = (remote or "").strip() or None
|
||||
org_filter = (org or "").strip() or None
|
||||
repo_filter = (repo or "").strip() or None
|
||||
role_filter = (role or "").strip() or None
|
||||
model_filter = (model or "").strip() or None
|
||||
stage_filter = (stage or "").strip() or None
|
||||
|
||||
try:
|
||||
db = control_plane_db.ControlPlaneDB(db_path=db_path)
|
||||
rows = db.query_usage_events(
|
||||
remote=remote_filter,
|
||||
org=org_filter,
|
||||
repo=repo_filter,
|
||||
project_id=project_id,
|
||||
role=role_filter,
|
||||
model=model_filter,
|
||||
stage=stage_filter,
|
||||
issue_number=issue_number,
|
||||
pr_number=pr_number,
|
||||
limit=limit,
|
||||
)
|
||||
except Exception as exc:
|
||||
empty_summary = aggregate_events("Overall", [])
|
||||
return AnalyticsSnapshot(
|
||||
ok=False,
|
||||
reason=f"control_plane_db_unavailable: {exc}",
|
||||
schema_version=ANALYTICS_SCHEMA_VERSION,
|
||||
remote=remote,
|
||||
org=org,
|
||||
repo=repo,
|
||||
total_events=0,
|
||||
overall_summary=empty_summary,
|
||||
by_project={},
|
||||
by_role={},
|
||||
by_model={},
|
||||
by_work_item={},
|
||||
by_stage={},
|
||||
events=(),
|
||||
)
|
||||
|
||||
parsed_events: list[UsageEvent] = []
|
||||
for r in rows:
|
||||
meta = console_redaction.redact_text(r.get("metadata")) if r.get("metadata") else None
|
||||
parsed_events.append(
|
||||
UsageEvent(
|
||||
usage_id=r["usage_id"],
|
||||
session_id=r.get("session_id"),
|
||||
remote=r.get("remote", remote),
|
||||
org=r.get("org", org),
|
||||
repo=r.get("repo", repo),
|
||||
project_id=r.get("project_id"),
|
||||
role=r.get("role", "unknown"),
|
||||
model=r.get("model", "unknown"),
|
||||
issue_number=r.get("issue_number"),
|
||||
pr_number=r.get("pr_number"),
|
||||
stage=r.get("stage", "unknown"),
|
||||
input_tokens=r.get("input_tokens"),
|
||||
output_tokens=r.get("output_tokens"),
|
||||
total_tokens=r.get("total_tokens"),
|
||||
estimated_cost_usd=r.get("estimated_cost_usd"),
|
||||
latency_ms=r.get("latency_ms"),
|
||||
duration_ms=r.get("duration_ms"),
|
||||
status=r.get("status", "success"),
|
||||
metadata=meta,
|
||||
created_at=r.get("created_at", ""),
|
||||
)
|
||||
)
|
||||
|
||||
overall_summary = aggregate_events("Overall", parsed_events)
|
||||
|
||||
# Group by project
|
||||
groups_by_project: dict[str, list[UsageEvent]] = {}
|
||||
for e in parsed_events:
|
||||
key = e.project_id or (f"{e.org}/{e.repo}" if e.org and e.repo else "default")
|
||||
groups_by_project.setdefault(key, []).append(e)
|
||||
by_project = {k: aggregate_events(k, v) for k, v in groups_by_project.items()}
|
||||
|
||||
# Group by role
|
||||
groups_by_role: dict[str, list[UsageEvent]] = {}
|
||||
for e in parsed_events:
|
||||
groups_by_role.setdefault(e.role, []).append(e)
|
||||
by_role = {k: aggregate_events(k, v) for k, v in groups_by_role.items()}
|
||||
|
||||
# Group by model
|
||||
groups_by_model: dict[str, list[UsageEvent]] = {}
|
||||
for e in parsed_events:
|
||||
groups_by_model.setdefault(e.model, []).append(e)
|
||||
by_model = {k: aggregate_events(k, v) for k, v in groups_by_model.items()}
|
||||
|
||||
# Group by work item
|
||||
groups_by_work_item: dict[str, list[UsageEvent]] = {}
|
||||
for e in parsed_events:
|
||||
if e.issue_number:
|
||||
key = f"issue #{e.issue_number}"
|
||||
elif e.pr_number:
|
||||
key = f"pr #{e.pr_number}"
|
||||
else:
|
||||
key = "unlinked"
|
||||
groups_by_work_item.setdefault(key, []).append(e)
|
||||
by_work_item = {k: aggregate_events(k, v) for k, v in groups_by_work_item.items()}
|
||||
|
||||
# Group by stage
|
||||
groups_by_stage: dict[str, list[UsageEvent]] = {}
|
||||
for e in parsed_events:
|
||||
groups_by_stage.setdefault(e.stage, []).append(e)
|
||||
by_stage = {k: aggregate_events(k, v) for k, v in groups_by_stage.items()}
|
||||
|
||||
return AnalyticsSnapshot(
|
||||
ok=True,
|
||||
reason="ok",
|
||||
schema_version=ANALYTICS_SCHEMA_VERSION,
|
||||
remote=remote,
|
||||
org=org,
|
||||
repo=repo,
|
||||
total_events=len(parsed_events),
|
||||
overall_summary=overall_summary,
|
||||
by_project=by_project,
|
||||
by_role=by_role,
|
||||
by_model=by_model,
|
||||
by_work_item=by_work_item,
|
||||
by_stage=by_stage,
|
||||
events=tuple(parsed_events),
|
||||
)
|
||||
|
||||
|
||||
def snapshot_to_dict(snapshot: AnalyticsSnapshot) -> dict[str, Any]:
|
||||
return snapshot.to_dict()
|
||||
@@ -1,201 +0,0 @@
|
||||
"""HTML views for the Model Usage & Performance Analytics console (#651)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from webui.analytics_loader import AnalyticsSnapshot, GroupMetrics, UsageEvent
|
||||
from webui.layout import render_page
|
||||
|
||||
|
||||
def _render_badge(text: str, badge_type: str = "muted") -> str:
|
||||
return f'<span class="badge badge-{badge_type}">{text}</span>'
|
||||
|
||||
|
||||
def _render_group_table(title: str, groups: dict[str, GroupMetrics], key_header: str = "Group") -> str:
|
||||
if not groups:
|
||||
return (
|
||||
f"<h3>{title}</h3>"
|
||||
'<div class="card"><p class="muted">No telemetry events recorded for this dimension.</p></div>'
|
||||
)
|
||||
|
||||
rows = []
|
||||
for key, g in sorted(groups.items(), key=lambda x: x[1].total_events, reverse=True):
|
||||
cost_cell = (
|
||||
f'<span class="accent">{g.display_cost}</span>'
|
||||
if g.events_with_cost > 0
|
||||
else _render_badge("Unknown")
|
||||
)
|
||||
tokens_cell = (
|
||||
g.display_tokens
|
||||
if g.events_with_tokens > 0
|
||||
else _render_badge("Unknown")
|
||||
)
|
||||
lat_p50 = (
|
||||
g.display_latency_p50
|
||||
if g.events_with_latency > 0
|
||||
else _render_badge("Unknown")
|
||||
)
|
||||
lat_p90 = (
|
||||
g.display_latency_p90
|
||||
if g.events_with_latency > 0
|
||||
else _render_badge("Unknown")
|
||||
)
|
||||
dur_avg = (
|
||||
g.display_duration_avg
|
||||
if g.events_with_duration > 0
|
||||
else _render_badge("Unknown")
|
||||
)
|
||||
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><strong>{key}</strong></td>"
|
||||
f"<td>{g.total_events}</td>"
|
||||
f"<td>{tokens_cell}</td>"
|
||||
f"<td>{cost_cell}</td>"
|
||||
f"<td>{lat_p50}</td>"
|
||||
f"<td>{lat_p90}</td>"
|
||||
f"<td>{dur_avg}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
|
||||
rows_html = "".join(rows)
|
||||
return f"""
|
||||
<h3>{title}</h3>
|
||||
<div class="card" style="overflow-x: auto;">
|
||||
<table class="data-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>{key_header}</th>
|
||||
<th>Events</th>
|
||||
<th>Total Tokens</th>
|
||||
<th>Est. Cost</th>
|
||||
<th>Latency (p50)</th>
|
||||
<th>Latency (p90)</th>
|
||||
<th>Avg Stage Duration</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{rows_html}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
"""
|
||||
|
||||
|
||||
def _render_events_table(events: tuple[UsageEvent, ...]) -> str:
|
||||
if not events:
|
||||
return (
|
||||
"<h3>Recent Usage & Instrumentation Events</h3>"
|
||||
'<div class="card"><p class="muted">No individual telemetry events recorded yet. Opt-in instrumentation via session logging or POST /api/v1/analytics/usage.</p></div>'
|
||||
)
|
||||
|
||||
rows = []
|
||||
for e in list(events)[-50:]: # Display latest 50
|
||||
work_item = f"issue #{e.issue_number}" if e.issue_number else (f"pr #{e.pr_number}" if e.pr_number else "unlinked")
|
||||
tokens = f"{e.total_tokens:,}" if e.total_tokens is not None else _render_badge("Unknown")
|
||||
cost = f"${e.estimated_cost_usd:.4f}" if e.estimated_cost_usd is not None else _render_badge("Unknown")
|
||||
latency = f"{e.latency_ms} ms" if e.latency_ms is not None else _render_badge("Unknown")
|
||||
duration = f"{e.duration_ms} ms" if e.duration_ms is not None else _render_badge("Unknown")
|
||||
status_badge = _render_badge(e.status, "success" if e.status == "success" else "danger")
|
||||
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td>#{e.usage_id}</td>"
|
||||
f"<td><small>{e.created_at}</small></td>"
|
||||
f"<td><span class=\"badge\">{e.role}</span></td>"
|
||||
f"<td><strong>{e.model}</strong></td>"
|
||||
f"<td>{e.stage}</td>"
|
||||
f"<td>{work_item}</td>"
|
||||
f"<td>{tokens}</td>"
|
||||
f"<td>{cost}</td>"
|
||||
f"<td>{latency}</td>"
|
||||
f"<td>{duration}</td>"
|
||||
f"<td>{status_badge}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
|
||||
rows_html = "".join(rows)
|
||||
return f"""
|
||||
<h3>Recent Telemetry Events</h3>
|
||||
<div class="card" style="overflow-x: auto;">
|
||||
<table class="data-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>ID</th>
|
||||
<th>Timestamp</th>
|
||||
<th>Role</th>
|
||||
<th>Model</th>
|
||||
<th>Stage</th>
|
||||
<th>Work Item</th>
|
||||
<th>Tokens</th>
|
||||
<th>Cost</th>
|
||||
<th>Latency</th>
|
||||
<th>Duration</th>
|
||||
<th>Status</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{rows_html}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
"""
|
||||
|
||||
|
||||
def render_analytics_page(snapshot: AnalyticsSnapshot) -> str:
|
||||
"""Render the main Model Usage & Performance Analytics console page."""
|
||||
summary = snapshot.overall_summary
|
||||
|
||||
kpi_tokens = summary.display_tokens if summary.events_with_tokens > 0 else _render_badge("Unknown")
|
||||
kpi_cost = summary.display_cost if summary.events_with_cost > 0 else _render_badge("Unknown")
|
||||
kpi_lat_p50 = summary.display_latency_p50 if summary.events_with_latency > 0 else _render_badge("Unknown")
|
||||
kpi_dur_avg = summary.display_duration_avg if summary.events_with_duration > 0 else _render_badge("Unknown")
|
||||
|
||||
status_notice = ""
|
||||
if not snapshot.ok:
|
||||
status_notice = (
|
||||
f'<div class="card warning-card"><strong>Degraded Data Source:</strong> {snapshot.reason}</div>'
|
||||
)
|
||||
|
||||
body_html = f"""
|
||||
<h2>Model Usage & Performance Analytics (Phase 4)</h2>
|
||||
<p class="muted">
|
||||
Durable console analytics for model usage, token cost, latency percentiles, and workflow-stage performance correlated to issues, PRs, and worker roles.
|
||||
</p>
|
||||
|
||||
{status_notice}
|
||||
|
||||
<div class="notice-card" style="background: rgba(91, 159, 212, 0.1); border: 1px solid var(--border); padding: 0.75rem 1rem; border-radius: 6px; margin-bottom: 1.5rem;">
|
||||
<small><strong>Note on telemetry fidelity:</strong> Missing data or untracked metrics are explicitly labeled as <em>Unknown</em>. No token costs or latency metrics are zero-fabricated.</small>
|
||||
</div>
|
||||
|
||||
<div class="card-grid" style="display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 1rem; margin-bottom: 1.5rem;">
|
||||
<div class="card">
|
||||
<span class="muted" style="font-size: 0.85rem;">Total Events</span>
|
||||
<h3 style="margin: 0.25rem 0 0 0;">{summary.total_events}</h3>
|
||||
</div>
|
||||
<div class="card">
|
||||
<span class="muted" style="font-size: 0.85rem;">Total Tokens</span>
|
||||
<h3 style="margin: 0.25rem 0 0 0;">{kpi_tokens}</h3>
|
||||
</div>
|
||||
<div class="card">
|
||||
<span class="muted" style="font-size: 0.85rem;">Est. Token Cost</span>
|
||||
<h3 style="margin: 0.25rem 0 0 0;">{kpi_cost}</h3>
|
||||
</div>
|
||||
<div class="card">
|
||||
<span class="muted" style="font-size: 0.85rem;">Latency (p50)</span>
|
||||
<h3 style="margin: 0.25rem 0 0 0;">{kpi_lat_p50}</h3>
|
||||
</div>
|
||||
<div class="card">
|
||||
<span class="muted" style="font-size: 0.85rem;">Avg Stage Duration</span>
|
||||
<h3 style="margin: 0.25rem 0 0 0;">{kpi_dur_avg}</h3>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{_render_group_table("Usage & Cost by Model", snapshot.by_model, "Model")}
|
||||
{_render_group_table("Performance by Workflow Stage", snapshot.by_stage, "Stage")}
|
||||
{_render_group_table("Usage & Cost by Role", snapshot.by_role, "Role")}
|
||||
{_render_group_table("Work Item Analytics", snapshot.by_work_item, "Work Item")}
|
||||
{_render_events_table(snapshot.events)}
|
||||
"""
|
||||
|
||||
return render_page(title="Model Usage & Performance Analytics", body_html=body_html)
|
||||
+20
-76
@@ -47,18 +47,13 @@ from webui.worktree_views import render_worktrees_page
|
||||
from webui.runtime_health import load_runtime_snapshot, snapshot_to_dict as runtime_snapshot_to_dict
|
||||
from webui.runtime_views import render_runtime_page
|
||||
from webui.timeline import load_timeline, snapshot_to_dict as timeline_snapshot_to_dict
|
||||
from webui.analytics_loader import (
|
||||
load_analytics,
|
||||
record_usage,
|
||||
snapshot_to_dict as analytics_snapshot_to_dict,
|
||||
)
|
||||
from webui.analytics_views import render_analytics_page
|
||||
from webui.system_health import (
|
||||
API_PATH as SYSTEM_HEALTH_API_PATH,
|
||||
load_system_health,
|
||||
process_uptime,
|
||||
snapshot_to_dict as system_health_to_dict,
|
||||
)
|
||||
from webui.system_health_views import render_system_health_page
|
||||
|
||||
_READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
|
||||
_AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"})
|
||||
@@ -167,6 +162,24 @@ async def api_system_health(request: Request) -> JSONResponse:
|
||||
return JSONResponse(payload, status_code=200 if snapshot.ready else 503)
|
||||
|
||||
|
||||
async def system_health(request: Request) -> HTMLResponse:
|
||||
"""Read-only system-health dashboard (#639).
|
||||
|
||||
Shares the #634 snapshot loader with the JSON API so the page can never
|
||||
disagree with it. `?deep=1` opts into the network probe exactly as the API
|
||||
does; the default page load stays cheap. The response is always 200: this
|
||||
is an operator view that must render the degraded state, not withhold it.
|
||||
"""
|
||||
deep = _truthy_flag(request.query_params.get("deep"))
|
||||
snapshot = load_system_health(deep=deep)
|
||||
return HTMLResponse(
|
||||
render_page(
|
||||
title="System health",
|
||||
body_html=render_system_health_page(snapshot),
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
async def queue(_request: Request) -> HTMLResponse:
|
||||
snapshot = load_queue_snapshot()
|
||||
return HTMLResponse(render_page(title="Queue", body_html=render_queue_page(snapshot)))
|
||||
@@ -554,72 +567,6 @@ async def api_v1_timeline(request: Request) -> JSONResponse:
|
||||
return JSONResponse(timeline_snapshot_to_dict(snapshot), status_code=status_code)
|
||||
|
||||
|
||||
async def analytics(request: Request) -> HTMLResponse:
|
||||
"""Read-only model usage, token cost, latency, and performance analytics HTML view (#651)."""
|
||||
snapshot = load_analytics(
|
||||
remote=request.query_params.get("remote"),
|
||||
org=request.query_params.get("org"),
|
||||
repo=request.query_params.get("repo"),
|
||||
role=request.query_params.get("role"),
|
||||
model=request.query_params.get("model"),
|
||||
stage=request.query_params.get("stage"),
|
||||
issue_number=_query_int(request, "issue"),
|
||||
pr_number=_query_int(request, "pr"),
|
||||
limit=_query_int(request, "limit") or 200,
|
||||
)
|
||||
return HTMLResponse(render_analytics_page(snapshot))
|
||||
|
||||
|
||||
async def api_v1_analytics(request: Request) -> JSONResponse:
|
||||
"""Read-only model usage, token cost, latency, and performance analytics API (#651)."""
|
||||
snapshot = load_analytics(
|
||||
remote=request.query_params.get("remote"),
|
||||
org=request.query_params.get("org"),
|
||||
repo=request.query_params.get("repo"),
|
||||
role=request.query_params.get("role"),
|
||||
model=request.query_params.get("model"),
|
||||
stage=request.query_params.get("stage"),
|
||||
issue_number=_query_int(request, "issue"),
|
||||
pr_number=_query_int(request, "pr"),
|
||||
limit=_query_int(request, "limit") or 500,
|
||||
)
|
||||
status_code = 200 if snapshot.ok else 500
|
||||
return JSONResponse(analytics_snapshot_to_dict(snapshot), status_code=status_code)
|
||||
|
||||
|
||||
async def api_v1_analytics_ingest(request: Request) -> JSONResponse:
|
||||
"""Optional session instrumentation ingestion endpoint (#651)."""
|
||||
try:
|
||||
body = await request.json()
|
||||
except Exception:
|
||||
return JSONResponse({"error": "invalid_json", "detail": "body must be valid JSON"}, status_code=400)
|
||||
|
||||
if not isinstance(body, dict):
|
||||
return JSONResponse({"error": "invalid_payload", "detail": "payload must be a JSON object"}, status_code=400)
|
||||
|
||||
usage_id = record_usage(
|
||||
session_id=body.get("session_id"),
|
||||
remote=body.get("remote", "dadeschools"),
|
||||
org=body.get("org", ""),
|
||||
repo=body.get("repo", ""),
|
||||
project_id=body.get("project_id"),
|
||||
role=body.get("role", "unknown"),
|
||||
model=body.get("model", "unknown"),
|
||||
issue_number=body.get("issue_number") or body.get("issue"),
|
||||
pr_number=body.get("pr_number") or body.get("pr"),
|
||||
stage=body.get("stage", "unknown"),
|
||||
input_tokens=body.get("input_tokens"),
|
||||
output_tokens=body.get("output_tokens"),
|
||||
total_tokens=body.get("total_tokens"),
|
||||
estimated_cost_usd=body.get("estimated_cost_usd"),
|
||||
latency_ms=body.get("latency_ms"),
|
||||
duration_ms=body.get("duration_ms"),
|
||||
status=body.get("status", "success"),
|
||||
metadata=body.get("metadata"),
|
||||
)
|
||||
return JSONResponse({"ok": True, "usage_id": usage_id}, status_code=201)
|
||||
|
||||
|
||||
async def method_not_allowed(request: Request, _exc: Exception) -> Response:
|
||||
path = request.url.path
|
||||
if path in _AUDIT_MUTATION_PATHS and request.method == "POST":
|
||||
@@ -643,6 +590,7 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
|
||||
Route("/", home, methods=["GET"]),
|
||||
Route("/health", health, methods=["GET"]),
|
||||
Route(SYSTEM_HEALTH_API_PATH, api_system_health, methods=["GET"]),
|
||||
Route("/system-health", system_health, methods=["GET"]),
|
||||
Route("/queue", queue, methods=["GET"]),
|
||||
Route("/api/queue", api_queue, methods=["GET"]),
|
||||
Route("/projects", projects, methods=["GET"]),
|
||||
@@ -660,10 +608,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
|
||||
Route("/runtime", runtime, methods=["GET"]),
|
||||
Route("/api/runtime", api_runtime, methods=["GET"]),
|
||||
Route("/api/v1/timeline", api_v1_timeline, methods=["GET"]),
|
||||
Route("/analytics", analytics, methods=["GET"]),
|
||||
Route("/api/analytics", api_v1_analytics, methods=["GET"]),
|
||||
Route("/api/v1/analytics", api_v1_analytics, methods=["GET"]),
|
||||
Route("/api/v1/analytics/usage", api_v1_analytics_ingest, methods=["POST"]),
|
||||
Route("/audit", audit, methods=["GET", "POST"]),
|
||||
Route("/api/audit", api_audit, methods=["GET", "POST"]),
|
||||
Route("/worktrees", worktrees, methods=["GET"]),
|
||||
|
||||
@@ -236,6 +236,25 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
|
||||
.badge-in-review {{ color: #9ec8f0; border-color: #3d5f7a; }}
|
||||
.badge-duplicate {{ color: #e0c27a; border-color: #6b5730; }}
|
||||
.badge-stale {{ color: #c9b8e8; border-color: #5a4a78; }}
|
||||
.badge-health-ok {{ color: #8fd19e; border-color: #3d6b4a; }}
|
||||
.badge-health-degraded {{ color: #e0c27a; border-color: #6b5730; }}
|
||||
.badge-health-down {{ color: #f0a8a8; border-color: #7a3b3b; }}
|
||||
.badge-health-skipped {{ color: var(--muted); }}
|
||||
.badge-health-unproven {{ color: #c9b8e8; border-color: #5a4a78; }}
|
||||
.health-card {{
|
||||
margin: 1.25rem 0;
|
||||
padding: 0.85rem 1rem 1rem;
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 8px;
|
||||
background: var(--surface);
|
||||
}}
|
||||
.health-card h3 {{ margin: 0 0 0.5rem; font-size: 1.05rem; }}
|
||||
.health-card h4 {{ margin: 1rem 0 0.35rem; font-size: 0.92rem; color: var(--muted); }}
|
||||
.health-headline {{ color: var(--text); font-size: 1rem; margin: 0 0 0.5rem; }}
|
||||
.health-degraded {{ border-left-color: #e0c27a; }}
|
||||
.health-stale {{ border-left-color: #f0a8a8; }}
|
||||
ul.reasons {{ margin: 0.35rem 0; padding-left: 1.15rem; color: var(--muted); font-size: 0.9rem; }}
|
||||
ul.reasons li {{ margin-bottom: 0.3rem; }}
|
||||
</style>
|
||||
{extra_head}
|
||||
</head>
|
||||
|
||||
+1
-1
@@ -38,6 +38,7 @@ class NavGroup:
|
||||
NAV_GROUPS: tuple[NavGroup, ...] = (
|
||||
NavGroup("Health", (
|
||||
NavItem("/health", "Liveness"),
|
||||
NavItem("/system-health", "System health"),
|
||||
)),
|
||||
NavGroup("Traffic", (
|
||||
NavItem("/queue", "Queue"),
|
||||
@@ -64,7 +65,6 @@ NAV_GROUPS: tuple[NavGroup, ...] = (
|
||||
)),
|
||||
NavGroup("Insights", (
|
||||
NavItem("/insights", "Insights", "stub"),
|
||||
NavItem("/analytics", "Analytics"),
|
||||
NavItem("/audit", "Audit"),
|
||||
)),
|
||||
)
|
||||
|
||||
@@ -0,0 +1,307 @@
|
||||
"""HTML views for the system-health dashboard (#639).
|
||||
|
||||
Renders the read-only :class:`~webui.system_health.SystemHealthSnapshot`
|
||||
produced by the Phase 1 system-health API (#634). The page offers no restart,
|
||||
reload, or process-kill control: those are Phase 2 work, and manual process
|
||||
kills are the contamination path #630 exists to prevent.
|
||||
|
||||
Every free-text field passes through :func:`webui.system_health.redact` before
|
||||
it reaches HTML, so a probe detail that captured a token or a credentialed URL
|
||||
cannot leak through the dashboard even though the API redacts it already.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import html
|
||||
|
||||
from webui.system_health import (
|
||||
STATUS_DEGRADED,
|
||||
STATUS_DOWN,
|
||||
STATUS_OK,
|
||||
STATUS_SKIPPED,
|
||||
STATUS_UNPROVEN,
|
||||
DependencyProbe,
|
||||
SystemHealthSnapshot,
|
||||
redact,
|
||||
)
|
||||
|
||||
_STATUS_BADGE_CLASS = {
|
||||
STATUS_OK: "badge-health-ok",
|
||||
STATUS_DEGRADED: "badge-health-degraded",
|
||||
STATUS_DOWN: "badge-health-down",
|
||||
STATUS_SKIPPED: "badge-health-skipped",
|
||||
STATUS_UNPROVEN: "badge-health-unproven",
|
||||
}
|
||||
|
||||
|
||||
def _safe(value: object) -> str:
|
||||
"""Escape free text for HTML after redacting anything secret-shaped.
|
||||
|
||||
Use this for every value that can carry arbitrary text — probe details,
|
||||
reasons, probe errors — because those are where a credential could ride
|
||||
along.
|
||||
"""
|
||||
return html.escape(redact(str(value)))
|
||||
|
||||
|
||||
def _esc(value: object) -> str:
|
||||
"""Escape a structured field for HTML without redacting it.
|
||||
|
||||
Commit SHAs, probe names, statuses, and timestamps are enumerated or
|
||||
machine-generated, never credential-bearing. They must not go through
|
||||
:func:`redact`: its opaque-token rule matches any 32-plus-character run,
|
||||
so a 40-character git SHA would render as ``[redacted]`` and the parity
|
||||
view — the one thing an operator reads this page for — would be blank.
|
||||
"""
|
||||
return html.escape(str(value))
|
||||
|
||||
|
||||
def _status_badge(status: str) -> str:
|
||||
css = _STATUS_BADGE_CLASS.get(status, "badge-health-unproven")
|
||||
return f'<span class="badge {css}">{_esc(status)}</span>'
|
||||
|
||||
|
||||
def _reason_list(reasons: tuple[str, ...], *, empty: str) -> str:
|
||||
if not reasons:
|
||||
return f"<p class='muted'>{html.escape(empty)}</p>"
|
||||
items = "".join(f"<li>{_safe(reason)}</li>" for reason in reasons)
|
||||
return f"<ul class='reasons'>{items}</ul>"
|
||||
|
||||
|
||||
def _readiness_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
"""Overall readiness.
|
||||
|
||||
``ready`` and ``readiness_complete`` are shown separately on purpose: a
|
||||
snapshot whose required probes never ran is not the same as one that ran
|
||||
them and passed, and collapsing the two would render an unproven green.
|
||||
"""
|
||||
if snapshot.ready and snapshot.readiness_complete:
|
||||
headline = "Ready"
|
||||
elif snapshot.ready:
|
||||
headline = "Ready (incomplete evidence)"
|
||||
else:
|
||||
headline = "Not ready"
|
||||
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
f"<h3>Readiness {_status_badge(snapshot.status)}</h3>"
|
||||
f"<p class='health-headline'>{html.escape(headline)}</p>"
|
||||
"<table class='detail'>"
|
||||
f"<tr><th>Service</th><td><code>{_esc(snapshot.service)}</code></td></tr>"
|
||||
f"<tr><th>Mode</th><td>{_esc(snapshot.mode)}</td></tr>"
|
||||
f"<tr><th>Ready</th><td>{_esc(snapshot.ready)}</td></tr>"
|
||||
"<tr><th>Readiness evidence complete</th>"
|
||||
f"<td>{_esc(snapshot.readiness_complete)}</td></tr>"
|
||||
"<tr><th>Deep probes requested</th>"
|
||||
f"<td>{_esc(snapshot.deep_probes_requested)}</td></tr>"
|
||||
f"<tr><th>Observed at</th><td><code>{_esc(snapshot.timestamp)}</code></td></tr>"
|
||||
"</table>"
|
||||
"<h4>Readiness reasons</h4>"
|
||||
f"{_reason_list(snapshot.readiness_reasons, empty='No readiness objections recorded.')}"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _version_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
version = snapshot.version
|
||||
uptime_hours = snapshot.uptime_seconds / 3600.0
|
||||
known = (
|
||||
"resolved"
|
||||
if version.known
|
||||
else "unresolved — version fields could not be read from the checkout"
|
||||
)
|
||||
schema = version.control_plane_schema_version
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Version and uptime</h3>"
|
||||
"<table class='detail'>"
|
||||
f"<tr><th>Git SHA</th><td><code>{_esc(version.git_sha or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Git describe</th>"
|
||||
f"<td><code>{_esc(version.git_describe or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Control-plane schema</th>"
|
||||
f"<td>{_esc(schema if schema is not None else 'unknown')}</td></tr>"
|
||||
f"<tr><th>Python</th><td><code>{_esc(version.python_version)}</code></td></tr>"
|
||||
f"<tr><th>Version status</th><td>{html.escape(known)}</td></tr>"
|
||||
f"<tr><th>Started at</th><td><code>{_esc(snapshot.started_at)}</code></td></tr>"
|
||||
"<tr><th>Uptime</th>"
|
||||
f"<td>{snapshot.uptime_seconds:.3f}s ({uptime_hours:.2f}h)</td></tr>"
|
||||
"</table>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _dependency_rows(probes: tuple[DependencyProbe, ...]) -> str:
|
||||
if not probes:
|
||||
return "<p class='muted'>No dependency probes were reported.</p>"
|
||||
rows = []
|
||||
for probe in probes:
|
||||
latency = (
|
||||
f"{probe.latency_ms:.1f} ms" if probe.latency_ms is not None else "n/a"
|
||||
)
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><code>{_esc(probe.name)}</code></td>"
|
||||
f"<td>{_esc(probe.kind)}</td>"
|
||||
f"<td>{_status_badge(probe.status)}</td>"
|
||||
f"<td>{_esc('required' if probe.required else 'optional')}</td>"
|
||||
f"<td>{html.escape(latency)}</td>"
|
||||
f"<td>{_safe(probe.detail)}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
return (
|
||||
"<table class='registry'><thead><tr>"
|
||||
"<th>Dependency</th><th>Kind</th><th>Status</th><th>Requirement</th>"
|
||||
"<th>Latency</th><th>Detail</th>"
|
||||
"</tr></thead><tbody>"
|
||||
f"{''.join(rows)}</tbody></table>"
|
||||
)
|
||||
|
||||
|
||||
def _dependency_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
degraded = [probe for probe in snapshot.dependencies if probe.ran and not probe.healthy]
|
||||
not_run = [probe for probe in snapshot.dependencies if not probe.ran]
|
||||
|
||||
banner = ""
|
||||
if degraded:
|
||||
names = ", ".join(sorted(probe.name for probe in degraded))
|
||||
banner += (
|
||||
"<div class='stub health-degraded'><p><strong>Degraded dependencies:</strong> "
|
||||
f"{_esc(names)}</p></div>"
|
||||
)
|
||||
if not_run:
|
||||
names = ", ".join(sorted(probe.name for probe in not_run))
|
||||
banner += (
|
||||
"<div class='stub'><p><strong>Not probed:</strong> "
|
||||
f"{_esc(names)} — these contribute no evidence and are not counted "
|
||||
"as healthy.</p></div>"
|
||||
)
|
||||
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Dependencies</h3>"
|
||||
f"{banner}"
|
||||
f"{_dependency_rows(snapshot.dependencies)}"
|
||||
"<p class='muted'>Details are redacted at the API boundary and again "
|
||||
"before rendering; credentials are never displayed.</p>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _namespace_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
if not snapshot.mcp_namespaces:
|
||||
body = "<p class='muted'>No MCP namespaces are declared.</p>"
|
||||
else:
|
||||
rows = []
|
||||
for entry in snapshot.mcp_namespaces:
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><code>{_esc(entry.get('namespace'))}</code></td>"
|
||||
f"<td><code>{_esc(entry.get('required_tool'))}</code></td>"
|
||||
f"<td>{_status_badge(str(entry.get('status') or STATUS_UNPROVEN))}</td>"
|
||||
f"<td>{_esc(entry.get('ide_namespace_proven'))}</td>"
|
||||
f"<td>{_safe(entry.get('reason'))}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
body = (
|
||||
"<table class='registry'><thead><tr>"
|
||||
"<th>Namespace</th><th>Required tool</th><th>Status</th>"
|
||||
"<th>IDE-proven</th><th>Reason</th>"
|
||||
"</tr></thead><tbody>"
|
||||
f"{''.join(rows)}</tbody></table>"
|
||||
)
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>MCP namespaces</h3>"
|
||||
f"{body}"
|
||||
"<p class='muted'>The web process runs outside the IDE-managed MCP "
|
||||
"client, so namespace health is reported as unproven rather than "
|
||||
"guessed (#543).</p>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _stale_runtime_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
stale = snapshot.stale_runtime
|
||||
if stale.stale:
|
||||
warning = (
|
||||
"<div class='stub health-stale'><p><strong>Stale runtime:</strong> "
|
||||
"the running code, the checkout, and the remote-tracking commit "
|
||||
"disagree. Capability gates may be evaluating obsolete code — "
|
||||
"do not treat this runtime as mutation-safe.</p></div>"
|
||||
)
|
||||
elif not stale.determinable:
|
||||
warning = (
|
||||
"<div class='stub health-stale'><p><strong>Staleness "
|
||||
"indeterminate:</strong> parity could not be proven, so this "
|
||||
"runtime is not reported as mutation-safe.</p></div>"
|
||||
)
|
||||
else:
|
||||
warning = ""
|
||||
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Stale-runtime parity</h3>"
|
||||
f"{warning}"
|
||||
"<table class='detail'>"
|
||||
"<tr><th>Daemon head</th>"
|
||||
f"<td><code>{_esc(stale.daemon_head or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Checkout head</th>"
|
||||
f"<td><code>{_esc(stale.checkout_head or 'unknown')}</code></td></tr>"
|
||||
"<tr><th>Remote head</th>"
|
||||
f"<td><code>{_esc(stale.remote_head or 'unknown')}</code></td></tr>"
|
||||
f"<tr><th>Stale</th><td>{_esc(stale.stale)}</td></tr>"
|
||||
f"<tr><th>Determinable</th><td>{_esc(stale.determinable)}</td></tr>"
|
||||
f"<tr><th>Mutation safe</th><td>{_esc(stale.mutation_safe)}</td></tr>"
|
||||
"</table>"
|
||||
f"{_reason_list(stale.reasons, empty='Runtime, checkout, and remote agree.')}"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _probe_error_card(snapshot: SystemHealthSnapshot) -> str:
|
||||
if not snapshot.probe_errors:
|
||||
return ""
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Probe errors</h3>"
|
||||
f"{_reason_list(snapshot.probe_errors, empty='')}"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def _recovery_card() -> str:
|
||||
"""Sanctioned recovery pointers only — never a manual process kill (#630)."""
|
||||
return (
|
||||
"<section class='health-card'>"
|
||||
"<h3>Recovery</h3>"
|
||||
"<p class='muted'>This dashboard is read-only. Restart and reload "
|
||||
"controls arrive in Phase 2 (#642); until then recovery runs through "
|
||||
"the sanctioned client reconnect / operator restart path.</p>"
|
||||
"<ul class='reasons'>"
|
||||
"<li><a href='/runtime'>Runtime and session view</a> — active profile, "
|
||||
"workflow hashes, and shell health.</li>"
|
||||
"<li>Reconnect the MCP client from the IDE, then re-run the blocked "
|
||||
"cycle. Never kill the daemon process manually: unmanaged kills are "
|
||||
"recorded as runtime contamination (#630).</li>"
|
||||
"<li>See <code>docs/webui-local-dev.md</code> for the documented "
|
||||
"recovery sequence.</li>"
|
||||
"</ul>"
|
||||
"</section>"
|
||||
)
|
||||
|
||||
|
||||
def render_system_health_page(snapshot: SystemHealthSnapshot) -> str:
|
||||
"""Render the full system-health dashboard body."""
|
||||
return (
|
||||
"<h2>System health</h2>"
|
||||
"<p class='meta'>Read-only view of the Phase 1 system-health API "
|
||||
"(<code>/api/v1/system/health</code>). Reload this page to refresh; "
|
||||
"nothing here polls or mutates on your behalf.</p>"
|
||||
f"{_readiness_card(snapshot)}"
|
||||
f"{_stale_runtime_card(snapshot)}"
|
||||
f"{_version_card(snapshot)}"
|
||||
f"{_dependency_card(snapshot)}"
|
||||
f"{_namespace_card(snapshot)}"
|
||||
f"{_probe_error_card(snapshot)}"
|
||||
f"{_recovery_card()}"
|
||||
)
|
||||
Reference in New Issue
Block a user