← 文章 / 云原生与基础设施
signoz 12天前 · 2026-11-10 21:10:34 · 11 阅读

基于 OpenTelemetry 的 Hermes 监控与可观测性

Hermes Agent 是 Nous Research 推出的开源自主 AI 助手。它具备跨会话记忆能力,能根据经验生成自有技能,通过派生子代理实现并行任务处理,并支持无人值守的定时任务执行。你可以通过终端或 Telegram、Discord、Slack、WhatsApp、Signal 及电子邮件等渠道与其交互。

这种设计特性使得 Hermes 在缺乏遥测数据时难以追踪:会话生命周期长,技能集动态变化,子代理独立运行且不可见,定时任务在无人监控时触发。

本指南将指导你使用 OpenTelemetry 设置 Hermes 的监控与可观测性,并将追踪、指标和日志数据导出至 SigNoz。通过此集成方案,你可以监控代理会话、LLM 调用、工具执行、技能运行及子代理操作。

借助 SigNoz 中的完整 Hermes 监控功能,你可以在统一仪表盘中关联分析追踪、日志和指标,针对延迟和错误配置告警,并识别导致成本上升和故障的模型、技能及工具。

前置条件

使用 OpenTelemetry 实现 Hermes 监控插桩

有关使用 OpenTelemetry 对 Hermes 进行插桩的详细信息,请参考 hermes-otel 插件 文档。

步骤 1:安装 Hermes Agent

Copy
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

如果 hermes 命令立即可用,请重启 Shell 或加载 Shell 配置文件。

验证安装:

Copy
hermes --version

若为新安装的 Hermes,请运行设置向导:

Copy
hermes setup

步骤 2:安装 OpenTelemetry 插件

Copy
hermes 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 来安装:

Copy
find ~/.hermes -path '*/venv/bin/pip' -print
/path/that/was/printed/bin/pip install -e ~/.hermes/plugins/hermes_otel

确认插件已启用:

Copy
hermes plugins list --plain --no-bundled | grep hermes_otel

输出中应能看到 hermes_otel 处于启用状态。

第 3 步:添加 SigNoz 环境变量

编辑 Hermes 的环境文件 ~/.hermes/.env,加入以下内容:

Copy
OTEL_SIGNOZ_ENDPOINT=https://ingest.<region>.signoz.cloud:443/v1/traces
OTEL_SIGNOZ_INGESTION_KEY=<your-ingestion-key>
OTEL_PROJECT_NAME=hermes-agent
使用自托管 SigNoz?

大部分步骤完全相同。只需按照 Cloud → Self-Hosted 文档调整 endpoint,并去掉 ingestion key 请求头即可。

第 4 步:配置 traces、metrics 和 logs

创建或编辑插件配置:

Copy
mkdir -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 端点。

Info

使用显式的 backends: 条目可让配置具备可复现性,启用全部三类信号(traces、metrics 和 logs),并通过 ingestion_key_env 将密钥存储在 .env 中,避免在 YAML 文件里硬编码。

第 5 步:重启 Hermes

配置在进程启动时读取。对于 gateway 服务,请执行:

Copy
hermes gateway restart

对于 CLI/TUI 使用场景,请退出 Hermes 后重新启动:

Copy
hermes

第 6 步:生成遥测数据

执行一个简单的 Hermes 交互:

Copy
hermes chat -q "Say hello and list the current working directory using a tool."

这会生成 agent 根 span、LLM/API span、(如果使用了工具)工具 span、Hermes 指标以及 Python 日志记录。

第 7 步:本地验证

检查插件启动日志:

Copy
grep -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

你也可以在不暴露密钥的情况下验证配置解析:

Copy
PYTHONPATH=$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

预期输出:

Copy
capture_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 标签页中查看:

Hermes Trace View
Hermes Trace 视图

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

Hermes Detailed Trace View
Hermes Trace 详情视图

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

Related logs
Related logs 按钮
Hermes Logs
SigNoz Logs 标签页中显示的 Hermes 日志

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

Hermes Detailed Log View
Hermes 日志详情视图

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

Hermes Metrics
SigNoz Metrics 标签页中显示的 Hermes 指标

点击 SigNoz 中的某个指标,可以看到它的详细信息,包括属性:

带有属性的 Hermes 指标详细视图

在 AI 可观测性中查看

AI 可观测性面板展示了 Hermes Agent 发起的 LLM 调用的成本、Token 消耗、延迟及错误。在 SigNoz 中,打开 AI 可观测性,并在 service_name 筛选器中选择你的服务。

LLM 调用的成本、Token 和延迟面板的 AI 可观测性概览仪表盘
AI 可观测性概览仪表盘

若要查询单条 Trace,请打开 Explorer 选项卡。Trace View 每条 Trace 显示一行,包含 Token 总数、成本及调用次数等汇总数据。你可以基于这些汇总数据进行过滤、聚合和排序,例如 trace.total_tokens > 1000。详情请参阅 AI 可观测性 Explorer。

如果面板始终为空,请确认你的 Span 包含了 遥测要求 中列出的属性。如需映射其他属性名称,请使用 属性映射 功能。

Hermes 监控仪表盘

你还可以使用我们定制的 Hermes Agent 仪表盘,它提供了专门用于监控 Hermes 使用情况的可视化图表。该仪表盘包含针对 LLM 使用场景预置的图表,并附有导入说明,助你快速上手。

Hermes 仪表盘
原始来源: signoz

评论 (0)