mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
0537cbfde4
## Description Persist bounded, aggregate-only Lifetime dashboard metrics across proxy restarts and expose them through a new `/stats-lifetime` endpoint. The change keeps session/runtime stats separate from durable lifetime stats, gates sensitive dashboard metadata for loopback or explicitly trusted dashboard clients, and updates the dashboard Lifetime view to consume the new endpoint. Closes #2137 ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [x] Code refactoring (no functional changes) ## Changes Made - Added bounded persistent lifetime metrics state and wired proxy metric events into it. - Added `/stats-lifetime` with sensitive project/persistence details gated behind dashboard metadata access checks. - Extended loopback/dashboard metadata access policy for trusted dashboard client CIDRs without widening admin/debug endpoints. - Reorganized dashboard session/lifetime presentation around runtime counters versus durable aggregates. - Added focused tests for persistent aggregation, persistence, endpoint registration, loopback gating, trusted dashboard CIDRs, and recent request ordering. - Fixed current Ruff/mypy issues in the lifetime metrics normalization code. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check`) - [x] Type checking passes (`mypy`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text uv run --extra proxy --with pytest --with pytest-asyncio pytest tests/test_persistent_metrics.py tests/test_persistent_metrics_integration.py tests/test_persistent_metrics_persistence.py tests/test_proxy_loopback_gating.py tests/test_proxy_stats_recent_requests.py -q 53 passed, 1 warning uvx ruff==0.15.17 check headroom/proxy/forwarded_headers.py headroom/proxy/loopback_guard.py headroom/proxy/persistent_metrics.py headroom/proxy/savings_tracker.py headroom/proxy/server.py tests/test_forwarded_headers.py tests/test_persistent_metrics.py tests/test_persistent_metrics_integration.py tests/test_persistent_metrics_persistence.py tests/test_proxy_loopback_gating.py tests/test_proxy_project_savings.py tests/test_proxy_stats_recent_requests.py All checks passed! uv run --extra proxy --with mypy mypy headroom/proxy/persistent_metrics.py Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Windows review worktree, Python 3.13.3 via uv. - Exact command / steps: Ran the focused persistent metrics, persistence, loopback gating, and recent request tests; ran CI-matching Ruff on touched files; ran mypy on the new persistent metrics module. - Observed result: `/stats-lifetime` is registered, non-loopback callers receive only non-sensitive aggregate data, loopback/trusted dashboard clients receive the full lifetime payload, admin/debug endpoints remain loopback-only, and persistent metrics normalize malformed stored state without type/lint errors. - Not tested: Full repository pytest suite, full dashboard browser screenshot pass, or live long-running proxy traffic. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A ## Additional Notes No changelog entry is required for this dashboard/internal metrics iteration. The endpoint intentionally exposes only aggregate lifetime data to ordinary network callers and strips project/persistence details unless the caller passes the dashboard metadata access policy. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
87 lines
3.1 KiB
Python
87 lines
3.1 KiB
Python
"""Tests schema v5 persistence around the pure Lifetime aggregate."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
|
|
from headroom.proxy.savings_tracker import SavingsTracker
|
|
|
|
|
|
def test_savings_tracker_migrates_v4_lifetime_to_v5_metrics_and_preserves_legacy_state(tmp_path):
|
|
path = tmp_path / "proxy_savings.json"
|
|
legacy_state = {
|
|
"schema_version": 4,
|
|
"lifetime": {
|
|
"requests": 7,
|
|
"tokens_saved": 20,
|
|
"compression_savings_usd": 0.5,
|
|
"cache_read_tokens": 5,
|
|
"cache_savings_usd": 0.2,
|
|
"total_input_tokens": 80,
|
|
"total_input_cost_usd": 1.5,
|
|
},
|
|
"display_session": {
|
|
"requests": 2,
|
|
"tokens_saved": 4,
|
|
"compression_savings_usd": 0.1,
|
|
"cache_read_tokens": 1,
|
|
"cache_savings_usd": 0.01,
|
|
"total_input_tokens": 10,
|
|
"total_input_cost_usd": 0.2,
|
|
"started_at": "2026-07-01T00:00:00Z",
|
|
"last_activity_at": "2026-07-02T00:00:00Z",
|
|
},
|
|
"history": [
|
|
{
|
|
"timestamp": "2026-07-02T00:00:00Z",
|
|
"total_tokens_saved": 20,
|
|
"compression_savings_usd": 0.5,
|
|
"total_input_tokens": 80,
|
|
"total_input_cost_usd": 1.5,
|
|
}
|
|
],
|
|
"projects": {"keep-me": {"requests": 1}},
|
|
}
|
|
path.write_text(json.dumps(legacy_state), encoding="utf-8")
|
|
|
|
tracker = SavingsTracker(path=str(path), save_flush_every=25)
|
|
lifetime = tracker.lifetime_response()
|
|
|
|
assert lifetime["schema_version"] == 5
|
|
assert lifetime["requests"]["total"] == 7
|
|
assert lifetime["tokens"]["input"] == 80
|
|
assert lifetime["tokens"]["attempted_input"] == 100
|
|
assert lifetime["tokens"]["saved"] == 20
|
|
assert lifetime["prefix_cache"]["cache_read_tokens"] == 5
|
|
assert lifetime["cost"] == {
|
|
"input_usd": 1.5,
|
|
"compression_savings_usd": 0.5,
|
|
"cache_savings_usd": 0.2,
|
|
}
|
|
assert lifetime["by_model"]["other"]["input_tokens"] == 80
|
|
|
|
tracker.flush()
|
|
saved = json.loads(path.read_text(encoding="utf-8"))
|
|
assert saved["schema_version"] == 5
|
|
assert saved["lifetime"] == legacy_state["lifetime"]
|
|
assert saved["display_session"]["requests"] == 2
|
|
assert saved["projects"]["keep-me"]["requests"] == 1
|
|
assert saved["lifetime_metrics"]["models"]["other"]["input_tokens"] == 80
|
|
assert isinstance(saved["lifetime_metrics"]["persistence"]["last_saved_at"], str)
|
|
|
|
|
|
def test_lifetime_response_reports_stateless_mode_without_writing(tmp_path):
|
|
path = tmp_path / "proxy_savings.json"
|
|
tracker = SavingsTracker(path=str(path), stateless=True, save_flush_every=1)
|
|
|
|
tracker.record_lifetime_request(provider="openai", stack="codex", model="gpt-test", input_tokens=3)
|
|
|
|
response = tracker.lifetime_response()
|
|
assert response["persistence"] == {
|
|
"enabled": False,
|
|
"healthy": True,
|
|
"error": "Lifetime metrics unavailable in stateless mode",
|
|
"pending_records": 0,
|
|
"last_saved_at": None,
|
|
}
|
|
assert path.exists() is False
|