Skip to main content

Quickstart

This walks you end-to-end: install the plugin, start a local Phoenix container, and watch a real Hermes turn show up as a span tree.

1. Install the plugin​

hermes-otel is a Hermes Agent plugin. From the plugin catalog:

hermes plugins install hermes-otel
hermes plugins enable hermes_otel

Or, until the catalog listing is merged, from this repository:

hermes plugins install briancaffey/hermes-otel/hermes_otel --enable

Either way the plugin lands at ~/.hermes/plugins/hermes_otel/, Hermes auto-discovers it via plugin.yaml, and Hermes 0.21+ installs the opentelemetry-* packages into its own venv for you. (On older Hermes builds, or after --no-deps, run <hermes venv>/bin/pip install -r ~/.hermes/plugins/hermes_otel/requirements.txt yourself; see Installation.)

2. Start a local Phoenix​

Phoenix is the fastest backend to spin up — a single container.

The Compose file lives in the repository, not in the installed plugin, so fetch it first:

mkdir -p ~/hermes-otel-backends && cd ~/hermes-otel-backends
curl -fsSLO https://raw.githubusercontent.com/briancaffey/hermes-otel/main/docker-compose/phoenix.yaml
docker compose -f phoenix.yaml up -d

Phoenix is now listening at:

3. Point the plugin at Phoenix​

Set the env var in your shell (or add it to ~/.hermes/.env):

export OTEL_PHOENIX_ENDPOINT="http://localhost:6006/v1/traces"
export OTEL_PROJECT_NAME="hermes-agent"

That's the entire configuration. No YAML needed for the single-backend case.

4. Run Hermes​

Start Hermes and send it a message that uses at least one tool — e.g. "list the files in my home directory":

hermes

The plugin prints a connection banner on startup:

[hermes-otel] ✓ Phoenix at http://localhost:6006/v1/traces (traces only)
[hermes-otel] ✓ Live dashboard store active
[hermes-otel] Registered 13 hooks

(The hook count depends on the Hermes version; 13 on Hermes 0.21.)

5. See the trace​

Open http://localhost:6006 in a browser. Pick the hermes-agent project and you'll see a full span tree:

agent
└── llm.claude-sonnet-4-6
    ├── api.claude-sonnet-4-6    prompt_tokens=312  completion_tokens=84
    │   └── tool.bash            args.command="ls -la ~"   outcome=completed
    └── api.claude-sonnet-4-6    prompt_tokens=518  completion_tokens=42

Each span carries:

  • User message on llm.* as input.value
  • Assistant response on llm.* as output.value
  • Tool arguments + result on tool.*
  • Token counts on api.*
  • Per-turn summary (tool count, tool names, final status) on the agent root

What's next?​

Something not showing up?

Enable debug logging — export HERMES_OTEL_DEBUG=true — and check ~/.hermes/plugins/hermes_otel/debug.log. Per-span start/end, parent nesting, token counts, and HTTP payloads all land there.