基于 OpenTelemetry 的 Hermes 监控与可观测性
Hermes Agent 是 Nous Research 推出的开源自主 AI 助手。它具备跨会话记忆能力,能根据经验生成自有技能,通过派生子代理实现并行任务处理,并支持无人值守的定时任务执行。你可以通过终端或 Telegram、Discord、Slack、WhatsApp、Signal 及电子邮件等渠道与其交互。
这种设计特性使得 Hermes 在缺乏遥测数据时难以追踪:会话生命周期长,技能集动态变化,子代理独立运行且不可见,定时任务在无人监控时触发。
本指南将指导你使用 OpenTelemetry 设置 Hermes 的监控与可观测性,并将追踪、指标和日志数据导出至 SigNoz。通过此集成方案,你可以监控代理会话、LLM 调用、工具执行、技能运行及子代理操作。
借助 SigNoz 中的完整 Hermes 监控功能,你可以在统一仪表盘中关联分析追踪、日志和指标,针对延迟和错误配置告警,并识别导致成本上升和故障的模型、技能及工具。
前置条件
- 一个拥有活跃摄入密钥的 SigNoz Cloud 账户,或 自托管 SigNoz 实例
- 一个 Hermes 实例。请遵循 Hermes 快速入门指南 完成初始配置
使用 OpenTelemetry 实现 Hermes 监控插桩
有关使用 OpenTelemetry 对 Hermes 进行插桩的详细信息,请参考 hermes-otel 插件 文档。
步骤 1:安装 Hermes Agent
Copycurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
如果 hermes 命令立即可用,请重启 Shell 或加载 Shell 配置文件。
验证安装:
Copyhermes --version
若为新安装的 Hermes,请运行设置向导:
Copyhermes setup
步骤 2:安装 OpenTelemetry 插件
Copyhermes plugins install briancaffey/hermes-otel --enable
插件安装路径如下:
Copy~/.hermes/plugins/hermes_otel/
将插件运行时依赖项安装到 Hermes Agent 的虚拟环境中:
Copy~/.hermes/hermes-agent/venv/bin/pip install -e ~/.hermes/plugins/hermes_otel
如果该路径不存在,先找到 Hermes 的 venv,用其中的 pip 来安装:
find ~/.hermes -path '*/venv/bin/pip' -print
/path/that/was/printed/bin/pip install -e ~/.hermes/plugins/hermes_otel
确认插件已启用:
Copyhermes plugins list --plain --no-bundled | grep hermes_otel
输出中应能看到 hermes_otel 处于启用状态。
第 3 步:添加 SigNoz 环境变量
编辑 Hermes 的环境文件 ~/.hermes/.env,加入以下内容:
OTEL_SIGNOZ_ENDPOINT=https://ingest.<region>.signoz.cloud:443/v1/traces
OTEL_SIGNOZ_INGESTION_KEY=<your-ingestion-key>
OTEL_PROJECT_NAME=hermes-agent
<region>:你的 SigNoz Cloud 区域<your-ingestion-key>:你的 SigNoz ingestion keyOTEL_PROJECT_NAME是你在 SigNoz 中看到的资源名称。
大部分步骤完全相同。只需按照 Cloud → Self-Hosted 文档调整 endpoint,并去掉 ingestion key 请求头即可。
第 4 步:配置 traces、metrics 和 logs
创建或编辑插件配置:
Copymkdir -p ~/.hermes/plugins/hermes_otel
${EDITOR:-nano} ~/.hermes/plugins/hermes_otel/config.yaml
使用下面这份最简配置:
Copy# Enable the plugin.
enabled: true
# Capture input/output previews on spans. Set false if you do not want prompt,
# tool, or response previews sent to SigNoz.
capture_previews: true
# Enable Python logging export through OpenTelemetry.
capture_logs: true
log_level: INFO
log_attach_logger: null
# Optional: metrics export interval. Lower values show metrics faster but send
# more requests.
flush_interval_ms: 60000
# Explicit SigNoz backend. This is the recommended reproducible config for
# traces + metrics + logs.
backends:
- type: signoz
endpoint: https://ingest.<region>.signoz.cloud:443/v1/traces
ingestion_key_env: OTEL_SIGNOZ_INGESTION_KEY
traces: true
metrics: true
logs: true
展开 25 行
将 <region> 替换为你的 SigNoz Cloud 区域(例如 us、eu 或 in)。如果你使用的是自托管 SigNoz,请将整个 endpoint: 值替换为你自己的 SigNoz OTLP HTTP traces 端点。
使用显式的 backends: 条目可让配置具备可复现性,启用全部三类信号(traces、metrics 和 logs),并通过 ingestion_key_env 将密钥存储在 .env 中,避免在 YAML 文件里硬编码。
第 5 步:重启 Hermes
配置在进程启动时读取。对于 gateway 服务,请执行:
Copyhermes gateway restart
对于 CLI/TUI 使用场景,请退出 Hermes 后重新启动:
Copyhermes
第 6 步:生成遥测数据
执行一个简单的 Hermes 交互:
Copyhermes chat -q "Say hello and list the current working directory using a tool."
这会生成 agent 根 span、LLM/API span、(如果使用了工具)工具 span、Hermes 指标以及 Python 日志记录。
第 7 步:本地验证
检查插件启动日志:
Copygrep -Ei 'hermes-otel|signoz|Logs' ~/.hermes/logs/*.log | tail -80
正常输出应包含类似以下内容的行:
Copy[hermes-otel] ✓ SigNoz at https://ingest.<region>.signoz.cloud:443/v1/traces
[hermes-otel] ✓ Logs → 1 backend(s) (attached to root, level=INFO)
[hermes-otel] Registered 8 hooks
你也可以在不暴露密钥的情况下验证配置解析:
CopyPYTHONPATH=$HOME/.hermes/plugins python - <<'PY'
from hermes_otel.plugin_config import load_config
from hermes_otel.backends import resolve
cfg = load_config()
print('capture_logs:', cfg.capture_logs)
print('backends_configured:', len(cfg.backends or ()))
for bc in cfg.backends or ():
b = resolve(bc)
print(f'backend={b.display_name} type={b.type} traces={b.supports_traces} metrics={b.supports_metrics} logs={b.supports_logs}')
print('endpoint:', b.endpoint)
PY
预期输出:
Copycapture_logs: True
backends_configured: 1
backend=SigNoz type=signoz traces=True metrics=True logs=True
endpoint: https://ingest.<region>.signoz.cloud:443/v1/traces
在 SigNoz 中查看 Hermes 的 Traces、Logs 和 Metrics
配置完成后,Hermes 应用会自动生成 traces、metrics 和 logs。在 SigNoz 中,可以找到一个名为 hermes-agent 的服务。
Hermes 的 traces 可以在 SigNoz 的 Traces 标签页中查看:

点击 SigNoz 中的某条 trace,可以看到它的详细信息,包括所有关联的 span 及其事件和属性。

Hermes 的 logs 可以在 SigNoz 的 Logs 标签页中查看。也可以在 trace 视图中点击“Logs”部分,查看与该 trace 关联的日志:


点击 SigNoz 中的某条日志,可以看到它的详细信息,包括属性:

Hermes 相关的 metrics 可以在 SigNoz 的 Metrics 标签页中查看:

点击 SigNoz 中的某个指标,可以看到它的详细信息,包括属性:
在 AI 可观测性中查看
AI 可观测性面板展示了 Hermes Agent 发起的 LLM 调用的成本、Token 消耗、延迟及错误。在 SigNoz 中,打开 AI 可观测性,并在 service_name 筛选器中选择你的服务。

若要查询单条 Trace,请打开 Explorer 选项卡。Trace View 每条 Trace 显示一行,包含 Token 总数、成本及调用次数等汇总数据。你可以基于这些汇总数据进行过滤、聚合和排序,例如 trace.total_tokens > 1000。详情请参阅 AI 可观测性 Explorer。
如果面板始终为空,请确认你的 Span 包含了 遥测要求 中列出的属性。如需映射其他属性名称,请使用 属性映射 功能。
Hermes 监控仪表盘
你还可以使用我们定制的 Hermes Agent 仪表盘,它提供了专门用于监控 Hermes 使用情况的可视化图表。该仪表盘包含针对 LLM 使用场景预置的图表,并附有导入说明,助你快速上手。