304 lines
10 KiB
Python
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},
|
|
)
|