5.2 KiB
hermes-trace Hook Implementation
Capture Mechanism
Uses 3 official Hermes plugin hooks — the same mechanism as the bundled Langfuse plugin.
Hook Registration (in __init__.py)
# __init__.py
import threading
from .hooks import on_post_api_request, on_post_tool_call, on_pre_api_request
from .launcher import _cleanup_loop, _run_frontend
def register(ctx):
# Configuration and database initialization happen before this wiring.
ctx.register_hook("pre_api_request", on_pre_api_request)
ctx.register_hook("post_api_request", on_post_api_request)
ctx.register_hook("post_tool_call", on_post_tool_call)
threading.Thread(
target=_cleanup_loop, daemon=True, name="hermes-trace-cleanup"
).start()
threading.Thread(
target=_run_frontend, daemon=True, name="hermes-trace-frontend"
).start()
The handlers are implemented in hooks.py; the daemon targets are provided by
launcher.py. __init__.py keeps register() and re-exports the package
surface used by the plugin and its tests.
Why hooks, not middleware
| Aspect | Hooks (pre/post_api_request) |
Middleware (llm_execution) |
|---|---|---|
| Documented | ✅ Yes (official plugin docs) | ❌ No (internal, undocumented) |
| Used by | ✅ Langfuse plugin | ❌ No official plugin uses it |
| Signature | Stable, typed kwargs | May change without notice |
Hook Callbacks
pre_api_request
Fires before every LLM API call. Used to capture:
- Full request messages (conversation history + current prompt)
- Request preview (first 300 chars of the last non-system message)
Note: Background review fork detection (scanning for
_SKILL_REVIEW_PROMPT) is not yet implemented — all turns are currently stored without turn_type classification. This is tracked in PLAN.md as deferred.
post_api_request
Fires after every LLM API call. Used to capture:
- Response content and tool calls
- Token usage (input, output, total, cache_read, cache_write, reasoning)
- Latency (api_duration)
- Finish reason
- Full response payload
post_tool_call
Fires after each tool returns. Captures tool name, arguments, result, and duration.
⚠️ Error parameter limitation: The Hermes hook does not provide an
errorparameter — tool failure information is encoded in theresultfield. Thetool_calls.errorcolumn in the database schema exists but is alwaysNonebecause there is no error data available from the hook payload. Inspect theresultfield to detect tool failures.
Daemon Threads / Subprocess
Spawning pattern (in register()):
threading.Thread(target=_cleanup_loop, daemon=True, name="hermes-trace-cleanup").start()
threading.Thread(
target=_run_frontend, daemon=True, name="hermes-trace-frontend"
).start()
Both threads are daemon — they live as long as the Hermes process.
Cleanup Thread
- Runs every 60 minutes
- Deletes turns older than
retention_days(default: 7) - Tool calls deleted via
ON DELETE CASCADE
Frontend Subprocess
_run_frontend() is a daemon thread that:
- Acquires a singleton lock via
fcntl.flock(LOCK_EX | LOCK_NB)— only one Hermes process across all profiles runs the frontend. - Resolves the runtime — prefers the plugin's own
.venv/bin/python(verified via a subprocess preflight that checksgranian,fastapi, andjinja2are importable). If unavailable, logs an error and exits without retrying. - Kills orphan processes — reads a PID file +
/proc/<pid>/cmdlineto identify and terminate any lingering Granian from a previous crash. - Launches Granian via
subprocess.Popen()as a separate OS process. - Monitors and respawns — if Granian exits, sleeps 3 seconds and retries.
The loop is bounded by the
finallyblock which releases the lock, closes the file descriptor, and cleans up PID and lock files on exit.
Reason for subprocess: Granian's .serve() calls signal.signal() which only
works in the main thread of the main interpreter. Running it inside the Hermes
process would require blocking the Hermes event loop.
Plugin Configuration
Configuration is read from environment variables (not plugins_config):
| Env var | Default | Description |
|---|---|---|
HERMES_TRACE_DB_PATH |
$HERMES_HOME/telemetry/telemetry.db¹ |
SQLite database path |
HERMES_TRACE_HOST |
127.0.0.1 |
Granian bind address |
HERMES_TRACE_PORT |
7788 |
Frontend server port |
HERMES_TRACE_RETENTION_DAYS |
7 |
Days to keep turn data |
¹
$HERMES_HOME預設為~/.hermes(可透過環境變數覆蓋)。使用HERMES_HOME讓 database 自動跟隨 Hermes profile 切換。
In ~/.hermes/config.yaml, the plugin can be enabled/disabled but runtime config uses env vars:
plugins:
enabled:
- hermes-trace
Full Payload Storage
All fields stored unconditionally:
full_request: Normalized conversation transcript assembled from provider-bound request data (JSON)full_response: Sanitized response snapshot exposed by the Hermes observability hook (JSON)- Tool call args and result (JSON)
No conditional capture toggle. If storage space is a concern, lower retention_days.