hermes-trace/app.py

304 lines
10 KiB
Python

from __future__ import annotations
import json
import logging
import os
from datetime import UTC, datetime, timedelta, timezone
from typing import Any
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.staticfiles import StaticFiles
import db
logger = logging.getLogger(__name__)
app: FastAPI = FastAPI(title="hermes-trace")
# Mount static files
app.mount(
"/static",
StaticFiles(directory=os.path.join(os.path.dirname(__file__), "static")),
name="static",
)
# ── Error handlers ──────────────────────────────────────────────
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(
request: Request, exc: StarletteHTTPException
) -> HTMLResponse:
"""Return an HTML fragment for HTTP errors (e.g. 404, 422)."""
return HTMLResponse(
f"<div class='error'>HTTP {exc.status_code}: {exc.detail}</div>",
status_code=exc.status_code,
)
@app.exception_handler(Exception)
async def generic_exception_handler(request: Request, exc: Exception) -> HTMLResponse:
"""Catch-all: return 500 HTML instead of raw JSON."""
logger.exception(
"Unhandled exception processing request %s %s", request.method, request.url
)
return HTMLResponse(
"<div class='error'>Internal server error</div>",
status_code=500,
)
# ── Security headers middleware ─────────────────────────────────
@app.middleware("http")
async def add_security_headers(request: Request, call_next):
"""Add Content-Security-Policy and other security headers."""
response = await call_next(request)
response.headers["Content-Security-Policy"] = (
"default-src 'self'; "
"script-src 'self' 'unsafe-eval' https://unpkg.com https://cdn.jsdelivr.net; "
"style-src 'self' 'unsafe-inline'; "
"img-src 'self' data:; "
"connect-src 'self'"
)
response.headers["X-Content-Type-Options"] = "nosniff"
return response
_db_path: str = os.environ.get("HERMES_TRACE_DB_PATH", db.get_default_db_path())
_templates: Jinja2Templates = Jinja2Templates(
directory=os.path.join(os.path.dirname(__file__), "templates"),
)
# Initialise database connection
db.telemetry_db = db.TelemetryDB(_db_path)
db.telemetry_db.init_db()
def _commas(value: object) -> str:
"""Format an integer with thousands separator commas."""
try:
if isinstance(value, (int, float, str)):
return f"{int(value):,}"
except (TypeError, ValueError):
pass
return "0"
_templates.env.filters["commas"] = _commas
def _utc8(value: object) -> str:
"""Convert UTC ISO datetime string to 'YYYY-MM-DD HH:MM:SS' (UTC+8).
SQLite ``datetime('now')`` stores UTC; this shifts to Asia/Taipei time.
"""
if not value:
return ""
try:
dt = datetime.fromisoformat(str(value))
if dt.tzinfo is None:
dt = dt.replace(tzinfo=UTC)
return dt.astimezone(timezone(timedelta(hours=8))).strftime("%Y-%m-%d %H:%M:%S")
except (ValueError, TypeError):
return str(value)
_templates.env.filters["utc8"] = _utc8
def _nl(value: object) -> str:
"""Replace literal \\\\n with actual newlines for <pre> display."""
if not isinstance(value, str):
return str(value) if value is not None else ""
return value.replace("\\n", "\n")
_templates.env.filters["nl"] = _nl
@app.get("/", response_class=HTMLResponse)
async def session_list(request: Request) -> HTMLResponse:
"""Render the session list page."""
sessions: list[dict[str, Any]] = db.get_db().get_sessions(limit=None)
return _templates.TemplateResponse(
request,
"index.html",
{"sessions": sessions},
)
@app.get("/session/{session_id}", response_class=HTMLResponse)
async def session_detail(request: Request, session_id: str) -> HTMLResponse:
"""Render the session timeline view with flat table and overlay detail."""
turns: list[dict[str, Any]] = db.get_db().get_turns_with_preview(session_id)
total_turn_count: int = db.get_db().get_session_turn_count(session_id) or len(turns)
stats = db.get_db().get_session_stats(session_id)
# Per-turn tokens per second
for t in turns:
ot = t.get("output_tokens") or 0
em = t.get("elapsed_ms") or 0
if ot > 0 and em > 0:
t["toks_per_sec"] = ot / (em / 1000)
else:
t["toks_per_sec"] = None
return _templates.TemplateResponse(
request,
"session.html",
{
"session_id": session_id,
"turns": turns,
"total_turn_count": total_turn_count,
"avg_tps": stats["avg_tps"],
"avg_latency": stats["avg_latency"],
"known_duration_turns": stats["known_duration_turns"],
"total_tool_calls": stats["total_tool_calls"],
},
)
@app.get("/session/{session_id}/waterfall/{turn_id}", response_class=HTMLResponse)
async def waterfall_view(
request: Request, session_id: str, turn_id: int
) -> HTMLResponse:
"""Render the waterfall tree fragment for a single turn (middle pane)."""
turn: dict[str, Any] | None = db.get_db().get_turn_detail(turn_id)
if turn is None:
return HTMLResponse("<div class='error'>Turn not found</div>", status_code=404)
if turn.get("session_id") != session_id:
return HTMLResponse("<div class='error'>Turn not found</div>", status_code=404)
return _templates.TemplateResponse(
request,
"waterfall.html",
{"waterfall_turn": turn},
)
def _pretty_json(
raw: str | None, indent: int = 2, replace_nl: bool = True
) -> str | None:
"""Try to parse and pretty-print a JSON string. Returns None on failure.
Args:
raw: Raw JSON string to format.
indent: Spaces per indent level.
replace_nl: Replace \\n inside string values with actual newlines.
Keep True for small tool-call JSON; set False for large payloads
where expanding \\n would explode the output size (e.g. 800KB → MB+).
"""
if not raw:
return None
try:
obj = json.loads(raw)
formatted = json.dumps(obj, indent=indent, ensure_ascii=False)
if replace_nl:
# Show \n inside JSON string values as actual line breaks
return formatted.replace("\\n", "\n")
return formatted
except (json.JSONDecodeError, TypeError):
return None
@app.get("/turn/{turn_id}", response_class=HTMLResponse)
async def turn_detail(request: Request, turn_id: int) -> HTMLResponse:
"""Render an HTMX fragment showing lightweight turn detail."""
database = db.get_db()
turn: dict[str, Any] | None = database.get_turn_preview(turn_id)
if turn is None:
return HTMLResponse("<div class='error'>Turn not found</div>", status_code=404)
# Optional label info from timeline (passed as query params)
order_num: int | None = None
order_str = request.query_params.get("order")
if order_str is not None:
try:
order_num = int(order_str)
except (ValueError, TypeError):
pass
tool_name: str | None = request.query_params.get("tool")
# Optional focus on a specific tool call
focus_tc: int | None = None
focus_str = request.query_params.get("focus_tc")
if focus_str is not None:
try:
focus_tc = int(focus_str)
except (ValueError, TypeError):
pass
# Preview data is intentionally lightweight; complete payloads are loaded
# only by the JSON tab's lazy payload endpoint. User input is read from
# the request column separately so tool-loop turns show the actual message.
user_input: str = database.get_turn_user_input(turn_id)
response_content: str = str(turn.get("response_preview") or "")
# Tool calls in the preview are truncated to 80 chars; load full args
# and result for the detail overlay.
if turn.get("tool_calls"):
turn["tool_calls"] = database.get_turn_tool_calls(turn_id)
# Token breakdown values for Langfuse-style tooltip
toks = {
"input": turn.get("input_tokens") or 0,
"output": turn.get("output_tokens") or 0,
"total": turn.get("total_tokens") or 0,
"cache_read": turn.get("cache_read_tokens"),
"cache_write": turn.get("cache_write_tokens"),
"reasoning": turn.get("reasoning_tokens"),
"input_usage_total": (turn.get("cache_read_tokens") or 0)
+ (turn.get("input_tokens") or 0),
"output_usage_total": turn.get("output_tokens") or 0,
}
return _templates.TemplateResponse(
request,
"turn_detail.html",
{
"turn": turn,
"user_input": user_input,
"response_content": response_content,
"toks": toks,
"pretty_tool_calls": [
{
"args_pretty": _pretty_json(tc.get("args")),
"result_pretty": _pretty_json(tc.get("result")),
}
for tc in (turn.get("tool_calls") or [])
],
"focus_tc": focus_tc,
"order_num": order_num,
"tool_name": tool_name,
},
)
@app.get("/turn/{turn_id}/payload", response_class=HTMLResponse)
async def turn_payload(request: Request, turn_id: int) -> HTMLResponse:
"""Lazy-load full request/response JSON text (avoids shipping MBs to DOM)."""
payload_type: str = request.query_params.get("type", "request")
if payload_type not in ("request", "response"):
return HTMLResponse("<div class='error'>Invalid type</div>", status_code=400)
payload: dict[str, Any] | None = db.get_db().get_turn_payload(turn_id, payload_type)
if payload is None:
return HTMLResponse("<div class='error'>Turn not found</div>", status_code=404)
field = f"full_{payload_type}"
raw: str = payload.get(field, "") or ""
formatted_json: str | None = _pretty_json(raw)
return _templates.TemplateResponse(
request,
"payload.html",
{"formatted_json": formatted_json},
)