Skip to content
telemetry.dev
Esc
↑↓navigate↵open⌘Jpreview
On this page

Hermes Agent

Export Hermes Agent turns, LLM calls, tool executions, sub-agents, and token metrics through the community hermes-otel plugin.

Hermes Agent runs as a CLI and as a gateway behind chat apps such as Telegram, Discord, and Slack. The community hermes-otel plugin turns each Hermes turn into an OpenTelemetry trace, with spans for LLM calls, API requests, tool calls, and sub-agents, and sends it with metrics to telemetry.dev over OTLP/HTTP.

hermes-otel is maintained by its author, not by telemetry.dev or Nous Research.

By default hermes-otel sends the complete prompt, including the system prompt and the whole conversation, and the complete response on every API call, plus previews of tool arguments and output. The setup below turns that off with content_capture: "off". See What leaves your machine.

Before you start

  • Hermes Agent 0.21 or later. Hermes installs the plugin’s Python dependencies automatically from that version on.
  • A telemetry.dev project and its API key. Keys start with td_live_.

Set up

Install and enable the plugin

hermes plugins install hermes_otel
hermes plugins enable hermes_otel

This installs the commit that the Hermes plugin catalog has reviewed. Installing doesn’t enable the plugin, so run both commands.

Set the API key

Export the key in the environment Hermes runs in, or add it to ~/.hermes/.env:

export TELEMETRY_DEV_API_KEY="td_live_..."

Point the plugin at telemetry.dev

Create ~/.hermes/hermes_otel.yaml:

content_capture: "off"

backends:
  - type: otlp
    name: telemetry-dev
    endpoint: https://api.telemetry.dev/v1/traces
    headers:
      Authorization: Bearer ${TELEMETRY_DEV_API_KEY}

Keep the quotes around "off": a bare off is YAML for false. The plugin replaces ${TELEMETRY_DEV_API_KEY} with the variable’s value when it loads the file. A type: otlp backend sends traces, metrics, and logs; logs flow only if you turn on log capture.

Restart Hermes

Restart any running Hermes gateway, then start hermes or send a message through the gateway.

Named profiles

Each Hermes profile has its own plugins and settings. The commands above set up the default profile, ~/.hermes. For a named profile, install and enable the plugin with -p, and save the same config in that profile’s home:

hermes -p <profile> plugins install hermes_otel
hermes -p <profile> plugins enable hermes_otel
~/.hermes/profiles/<profile>/hermes_otel.yaml

A profile without the plugin or without this file sends nothing to telemetry.dev. Within a profile, the same config covers CLI and gateway sessions, cron jobs, and sub-agent runs.

Check that data arrives

When Hermes starts, hermes-otel prints a startup banner with one [hermes-otel] ✓ line per backend. Look for the line with https://api.telemetry.dev/v1/traces, and for the content_capture=off notice.

Send a message, then open the trace explorer. Each turn is its own trace, and turns from one session share the session.id and gen_ai.conversation.id attributes. When a turn ends, the plugin flushes its spans in the background and waits up to 1.5 seconds (force_flush_wait_ms) before handing control back to Hermes.

If there is no banner, or no telemetry.dev line, run hermes plugins list to check that hermes_otel is enabled. If TELEMETRY_DEV_API_KEY isn’t set when Hermes starts, the plugin leaves ${TELEMETRY_DEV_API_KEY} in the header as literal text and telemetry.dev rejects the requests. Set HERMES_OTEL_DEBUG=true for a per-span debug log.

What is recorded

agent
├── skill.{name}
└── llm.{model}
    ├── api.{model}
    ├── tool.{name}
    ├── approval.{pattern}
    ├── subagent.{role}
    │   └── agent
    └── api.{model}
  • agent (or cron) is the turn, with its status and a summary of tools, commands, skills, and API calls.
  • llm.{model} records the model, the provider, and, unless content capture is off, the user message and the response.
  • api.{model} is one HTTP request to the provider, with token counts, cache and reasoning tokens, duration, and finish reason.
  • tool.{name} records each tool call’s outcome, the command or target the plugin infers from it, and, unless content capture is off, previews of its arguments and result.
  • subagent.{role} holds a delegated child run, so a multi-agent run is one trace.

Attributes follow the OpenTelemetry GenAI conventions (gen_ai.*), which telemetry.dev reads for model, provider, and token usage. The plugin also sends metrics, including gen_ai.client.token.usage and gen_ai.client.operation.duration, which appear under Metric series on the project Overview.

For every attribute and metric, see the hermes-otel span attribute and metric references.

What leaves your machine

content_capture controls conversation content on spans:

Value What is sent
full (default) The complete prompt, including the system prompt and every message, and the complete response on every api.* span. Clipped previews on other spans.
preview Clipped previews only, 1,200 characters each by default.
off No prompt, response, or tool content.

Because full puts the whole conversation so far on every api.* span, the same content is sent again on each API call in a turn. The older capture_previews: false setting still means off; an explicit content_capture wins.

Even with content_capture: "off", these are sent:

  • Tool names, outcomes, and the command and target the plugin infers from each tool call. hermes.tool.command and hermes.tool.target can contain shell commands, file paths, or URLs.
  • Token counts, model and provider names, timings, and all metrics.
  • Error text, cut to 500 characters: tool errors in error.message and the span status, provider errors in the span’s exception and status, and failed sub-agent summaries in the span status. Error text can quote file contents, commands, or other content.

Two more settings can add content, and both are off by default:

  • capture_logs: true forwards Python log records, whose bodies content_capture doesn’t cover. The plugin redacts secrets in them with Hermes’ redactor, but other text goes out as logged. It attaches to the root logger, so it exports logs from every library Hermes uses. Scope it with log_attach_logger, or leave it off.
  • capture_sender_id: true adds the chat platform’s sender ID to gateway sessions, which can identify users.

telemetry.dev’s privacy settings can also drop recognized content before storage, but only after it has left your machine.

Configuration

The plugin reads its settings from HERMES_OTEL_* environment variables first, then hermes_otel.yaml, then its defaults. For example, HERMES_OTEL_CONTENT_CAPTURE=off sets content_capture. For every setting, see the hermes-otel configuration docs and its config.yaml.example.

To run newer plugin code than the catalog has reviewed, install from the repository instead: hermes plugins install briancaffey/hermes-otel/hermes_otel --enable. That installs the latest main, which no one has reviewed for the catalog yet.

Last updated on October 29, 2026

Was this page helpful?