> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sazabi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Install the traceverse OpenTelemetry plugin in Hermes Agent to ship sessions, prompts, model responses with tokens and cost, and tool results to Sazabi as searchable logs.

[All Hermes Agent integration capabilities](https://docs.sazabi.com/catalogs/integrations/hermes-agent)

## About

Ship Hermes Agent session telemetry to Sazabi with `traceverse_hermes_otel`, an OpenTelemetry plugin from the Hermes plugin catalog. Hermes Agent has no agent telemetry export of its own; the plugin adds one with no code changes.

Every turn sends log events and trace spans over OTLP/HTTP:

* **Log events**, named by `event.name`: `session_start`, `user_prompt`, `api_response` (model, `input_tokens`, `output_tokens`, `cost_usd`, `finish_reason`, `ttft_ms`), and `tool_result` (`tool_name`, `status_code` of `success` or `error`). Every event carries `session.id`.
* **Spans**: `invoke_agent` for the turn, `chat` for each model call, and `execute_tool` for each tool call, with `gen_ai.*` attributes.

The gateway, cron jobs, and CLI sessions each send their own telemetry under the same service name.

> [!WARNING]
>
> `HERMES_OTEL_CAPTURE_CONTENT` is one switch for all text. Set to `true`, it exports prompts, model responses, and tool arguments and results together; the plugin cannot send prompts without responses. The setup below leaves it `false`. A failed tool's error text is exported either way.

## Prerequisites

* Hermes Agent with the `hermes plugins` and `hermes pm` commands
* Your Sazabi intake URL, shown above — open the log source and copy the **Intake URL** from its setup screen (the public key is embedded in the URL)

## Set up in the dashboard

**Step 1**

### Install and enable the OpenTelemetry plugin

Run these commands where Hermes is installed:

```bash title="Terminal" theme={"system"}
hermes pm install --extra otlp
hermes plugins install traceverse_hermes_otel
hermes plugins enable traceverse_hermes_otel
```

The first command adds the OpenTelemetry SDK and OTLP/HTTP exporter to Hermes' Python environment. Without them the plugin loads but sends nothing. Approve the dependency prompt if `hermes plugins install` shows one.

Each Hermes profile keeps its own plugin list. Enable the plugin in every profile you want telemetry from.

**Step 2**

### Point the plugin at Sazabi

Add these lines to `~/.hermes/.env`, or to the environment of the service or container that runs Hermes:

```bash title="~/.hermes/.env" theme={"system"}
HERMES_OTEL_ENDPOINT=<your intake URL>
HERMES_OTEL_SERVICE_NAME=hermes-agent
HERMES_OTEL_CAPTURE_CONTENT=false
```

Replace `<your intake URL>` with the intake URL shown above, with no path. The plugin appends `/v1/traces` and `/v1/logs` itself. The public key is part of the URL, so no auth header is needed.

The plugin prints the endpoint in its startup log line, so treat Hermes' own log files as sensitive.

**Step 3**

### Restart Hermes

Hermes reads its plugin list and `.env` when it starts. Restart the gateway (`hermes gateway restart`, or restart the service that runs it) and any open `hermes` sessions. Telemetry begins with the next turn.

## Set up with the CLI

You can also register the Hermes Agent log source with the [Sazabi CLI](https://docs.sazabi.com/reference/cli.md) (installed and authenticated — see [CLI reference](https://docs.sazabi.com/reference/cli/log-sources.md)).

Registering the source mints the same intake URL the dashboard shows above (the public key is embedded in its hostname):

```bash theme={"system"}
sazabi log-sources create hermes_agent --mode manual
```

The command prints the intake URL for the new source — copy the whole URL and point Hermes at it using the configuration shown above. Run `sazabi log-sources get <log-source-id>` at any time to reprint the endpoint, or `sazabi log-sources list` to see every log source in the project.

## Verify

Restart Hermes and send the agent one message. Hermes' log should show `OTel SDK tracer configured` and `OTel SDK logger configured`. Open the [Intake page](https://docs.sazabi.com/guides/instrument/intake.md) in the Sazabi dashboard and confirm logs from the **Hermes Agent** source appear within a minute or two.

From the CLI, `sazabi logs ask "How many hermes-agent log lines arrived in the last 15 minutes, by event.name?"` confirms rows are arriving, and `sazabi logs ask "Show failed Hermes tool calls in the last day"` lists `tool_result` events whose `status_code` is `error`.

## Troubleshooting

**`failed to configure OTel SDK tracer` in Hermes' log** — The OpenTelemetry SDK is missing from Hermes' Python environment. Run `hermes pm install --extra otlp` and restart Hermes.

**No logs after restarting** — Confirm `hermes plugins list` shows `traceverse_hermes_otel` enabled for the profile in use, and that `HERMES_OTEL_ENDPOINT` is set in that profile's `.env` or the service environment.

**Spans arrive but no log events** — `HERMES_OTEL_LOGS_ENABLED` is set to `false`. Remove it and restart Hermes.

**Input token counts look low** — For Anthropic models, `input_tokens` leaves out cached prompt tokens. Use `cost_usd` and `output_tokens` for spend trends.

## Further reading

> [card] [traceverse\_hermes\_otel plugin](https://hermes-agent.nousresearch.com/docs/plugins/traceverse_hermes_otel)
>
> The Hermes plugin catalog entry for the OpenTelemetry plugin.

> [card] [Intake](https://docs.sazabi.com/guides/instrument/intake.md)
>
> See per-source ingestion volume and health.

> [card] [Log sources](https://docs.sazabi.com/catalogs/log-sources.md)
>
> Browse the full log source catalog.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.