一键开启 Hermes Agent 可观测：成本归因、性能拆解与稳定性治理 - 文章 - 开发者社区

\点击上方👆蓝字关注我们！

picture.image

本文主要介绍火山引擎日志服务（TLS ）为 Hermes Agent 构建系统化可观测能力的完整过程，覆盖成本归因、性能拆解、稳定性监控与 Trace 链路追踪，并提供一键部署方案。

Hermes 原生观测的局限

在引入统一可观测方案之前，Hermes Agent 的排障手段主要依赖两类数据源：一是运行过程中产生的零散日志，二是本地的 ~/.hermes/state.db 状态数据库。

零散日志的问题在于缺乏统一结构。日志内容格式不一，想做趋势统计或者根因分析时，基本无从下手。至于 state.db，虽然记录了部分运行状态，但查询依赖 sqlite3 命令行，操作门槛不低，而且它并没有覆盖一些关键观测维度——比如工具调用的耗时分布、失败类型分类、分阶段耗时拆解等。

这些可观测手段上的不足，直接导致了几个反复出现的运维困境：

Token 成本缺乏归因能力 ：某天 Token 消耗突然上涨，团队想定位原因时，发现无法按 model、provider、platform 等维度拆分消耗。到底是某个模型的调用量增加了，还是某类 Session 的 Token 用量异常偏高？没有结构化数据，这些问题只能靠人肉排查。

性能瓶颈难以区分 ：用户反馈"感觉变慢了"，但 Agent 的一次交互涉及模型调用、工具执行、网络传输等多个环节。慢在哪里？是模型响应延迟增大，还是某个工具的执行时间变长？抑或是下游服务出现了限流？没有分阶段的耗时数据，根本无法给出准确判断。

故障归因缺少数据支撑 ：Error 日志数量增多时，我们能看到"出错了"，但很难快速回答"哪个模块出错最多""是偶发抖动还是持续劣化""影响范围有多大"这类关键问题。

picture.image

构建 Hermes 可观测体系

picture.image

针对上述痛点，我们将可观测能力拆解为四个相互关联的维度。每个维度对应一类典型的运维场景，四者组合起来构成一个相对完整的观测闭环。

成本归因：Token 消耗流向的精细化追踪

Token 是 Agent 运行最核心的成本项。我们需要回答的问题包括：总消耗的分布结构是什么样的？波动发生时，增量主要由哪个维度贡献？有没有异常的高消耗 Session？

具体而言，成本归因维度覆盖三个层面的能力：

成本波动根因 ：区分模型 / 工具 / Platform / 主机层面的消耗差异。
核心消耗定位 ：识别高贡献度的 Session。
异常检测 ：实时发现 Token 消耗的异常突增。

性能拆解：到底慢在哪一环

用户说"Agent 变慢了"，这句话本身信息量很低。一次完整的 Agent 交互可能串联了三四次模型调用和七八次工具执行，再加上网络往返，任何一个环节拖长都会让用户体感变差。所以性能分析的第一步不是"优化"，而是把耗时按环节拆开看。

我们在看板上提供了各阶段耗时的分布统计——模型响应花了多久、工具执行花了多久、排队等了多久，这些数据按 P50、P90、P99 分别呈现。P90 的趋势尤其值得盯住，因为很多性能退化不会体现在均值上，只有长尾开始恶化时，P90 才会率先给出信号。

稳定性监控：偶发抖动还是持续恶化

稳定性要回答的核心问题只有三个：哪个组件出了故障、故障持续了多久、影响面有多大。

看板会追踪每个工具、每个 provider 的失败次数和失败率。但光看"失败率上升了"远远不够——同样是失败率从 1% 涨到 5%，偶发性的网络超时和某个工具持续报错，处理策略完全是两回事。前者加个重试大概率就能兜住，后者如果不介入，失败率只会继续攀升。

所以我们在趋势图上做了按天聚合的呈现。连续三天失败率走高，基本可以排除偶发因素，这时候应该优先翻一翻最近有没有工具版本变更、下游依赖有没有做过发布。在我们的实际运维中，大约七成的趋势性劣化最终都能归因到某次配置变更或依赖升级上。

链路追踪：把一次对话的全过程摊开看

上面说的成本、性能、稳定性三个维度，提供的都是统计层面的视角——适合发现趋势、圈定范围，但不擅长回答"这一次对话到底发生了什么"。Trace 链路追踪补的就是这块能力。

一轮 Conversation 里，Agent 可能调了两次模型、五次工具，中间还有条件分支和错误重试。Trace 会把这些事件按时间顺序串成一条链，每个节点标注 Token 用量、执行耗时、成功或失败状态以及具体的报错内容。

这个能力最直接的用途是复现问题。遇到用户投诉"刚才那次对话结果不对"的时候，拿着 Session ID 去查 Trace，整个调用过程一目了然——哪一步拿到了什么输入、产出了什么结果、在哪个节点出了岔子。比起翻日志拼凑上下文，效率差距不止一个量级。

Hermes 观测看板设计

看板设计：总览先行，逐层收敛

看板的四个板块——模型调用、工具调用、Session 分析、Trace 链路——不是简单的并列关系，而是按照排障时的自然思路来编排的。

模型调用分析这个板块主要围绕 Token 成本展开。Token 消耗可以按模型、Provider、Platform、主机等维度拆解，配合按天聚合的趋势图来捕捉异常波动。

没有看板的时候，成本异常的排查往往要拉上好几个人翻半天日志。现在的做法简单得多：趋势图上看到哪天有跳变，点进去按模型或机器维度拆一下，很快就能圈出增量的来源。再往下钻到 Session 粒度，对照变更记录，几分钟基本能给出初步判断。

picture.image

工具调用：稳定性与链路瓶颈的核心观测点

看板首先给出的是一张全局健康度视图：工具总共被调了多少次、失败了多少次、失败率是多少、耗时分布长什么样。这张图的作用很简单——花十秒钟判断今天的工具调用整体上有没有问题。

再往下一层是以单个工具为粒度的画像。哪些工具调用量最大、哪些工具响应偏慢、哪些工具的失败率明显高于均值，在这个视图里一眼能看出来。我们内部有个不成文的习惯：每次新接入一个工具后，先跑两三天流量，专门盯它的画像数据，确认耗时和成功率在预期范围内再放量。

趋势层面，失败率和耗时都按天做了聚合。关注趋势图的核心目的是区分"今天偶尔抖了一下"和"连续三天在恶化"——后者的排查优先级要高得多，经验上应该第一时间翻最近的工具发版记录和下游依赖变更。

拿工具失败率上升这个场景说一下我们实际的排查思路：

第一步是看范围：是所有工具的失败率都在涨，还是集中在某一两个工具上？如果是全局性的，通常指向基础设施层面的问题；如果只有特定工具受影响，方向就明确了。
第二步针对出问题的 tool_name 做细分：报错集中在哪种类型？超时占比高不高？它依赖的下游服务最近有没有变更？
第三步才到主机层面——查 CPU 和内存有没有打满、网络有没有丢包、有没有触发限流策略。这三步走下来，大多数工具故障都能收敛到一个比较明确的方向。

picture.image

Session 分析：任务级别的全链路透视

多维度 Session 画像 ：支持按模型、Provider、Platform 等维度分析 Session 分布，识别高成本 / 低性能 / 高失败率的 Session 类型。
容量趋势分析 ：通过按天聚合的 Session 数量变化趋势，结合成本与失败率数据，提前发现可能的服务质量问题。

picture.image

Trace 链路追踪：端到端观测分析

Trace 链路追踪为 Hermes Agent Conversation 提供了端到端的全景观测能力，其核心价值在于将复杂的 Agent 交互过程转化为可量化、可下钻、可归因的结构化数据。

通过 Trace 追踪，可以实现对 Conversation 过程中各个关键节点 的精细化观测：

模型调用观测 ：精确记录每一次模型调用的 Token 消耗、响应耗时、调用成功/失败状态及详细错误信息。这使得 Token 消耗、时间消耗能够精准归因到具体的模型、Provider。
工具调用观测 ：深入观测 Agent 与外部工具的交互细节，包括工具的调用次数、执行耗时信息、调用成功/失败状态、失败类型（如超时、权限错误）及具体错误日志。
全链路上下文与交互详情 ：Trace 不仅记录离散的调用事件，更能串联起整个 Conversation 的上下文，包括输入输出、中间状态、调用序列等完整交互信息。这为问题复现、效果评估和持续优化提供了宝贵的原始数据。

picture.image

一键启用：观测看板自动就绪

本章节详细介绍如何快速启用 Hermes Agent 可观测能力，涵盖鉴权方式选型、安装部署、参数配置及验证等完整流程。

picture.image

鉴权方式选型

为满足不同安全级别的部署需求，提供 AK / SK 和 API Key 两种部署模式。AK / SK 模式适合首次体验或在开发环境中验证；如果对 AK / SK 有严格的管控需求的场景，则推荐采用 API Key 模式，避免 AK/SK 的泄漏风险。

使用限制：针对 Hermes Agent 的可观测功能现处于邀测阶段，如需体验，请联系客服。

部署前准备

部署前需要准备以下几个资源：

获取安全鉴权凭证 ：

AK / SK 模式： 在「访问控制 → API 访问密钥」中创建密钥对，且账户需要具备 TLS 项目与日志主题的创建权限。
API Key 模式： 在 TLS 控制台创建 Hermes Agent 应用和 API Key，记录各日志主题对应的 Topic ID 以及 API Key。

确认 Region 与 Endpoint ：根据数据存储的地域选择对应的接入点。

一键部署

复制以下命令，一键执行安装：

方式一：AK / SK 模式

  
curl -fsSL https://tls-hermes-cn-beijing.tos-cn-beijing.volces.com/install.sh | bash -s -- \  
  --region cn-beijing \  
  --ak {your_ak} \  
  --sk {your_sk} \  
  --endpoint tls-cn-beijing.volces.com \  
  --non-interactive

方式二：API Key 模式

  
curl -fsSL https://tls-hermes-cn-beijing.tos-cn-beijing.volces.com/install.sh | bash -s -- \  
  --region cn-beijing \  
  --api-key {your_api_key} \  
  --endpoint tls-cn-beijing.volces.com \  
  --non-interactive

部署后重启 Gateway

重启 Gateway

安装完毕后，需要重启 Gateway 以使插件生效：

  
hermes gateway restart

查看安装结果

重启后，可通过以下方式验证插件是否正常工作：

  
# 查看插件状态  
hermes plugins list  
  
# 检查可观测数据上报日志  
hermes logs | grep  tls

确认插件状态为 enabled，且日志中无错误信息即表示安装成功。

访问可观测看板

安装并验证成功后，通过以下路径访问可观测数据：

TLS 控制台 → 日志应用 → 已创建 APP 列表

管理员或授权用户选中目标 APP，即可直接访问该 Hermes Agent 实例的：

实时监控数据 ：Token 消耗趋势、工具调用健康度、Session 分布等核心指标。
链路追踪信息 ：端到端 Trace 详情，支持按 Session / 工具 / 模型等多个维度下钻。
性能分析报表 ：支持 P90 时延分布、性能趋势、性能瓶颈问题定位。

picture.image

后续方向

可观测能力的建设不会止步于当前版本。基于已经采集到的全链路数据，有几个方向是接下来会持续投入的。

一是利用观测数据反哺模型和工具的选型决策。当我们有了不同模型在不同任务类型下的性能和成本数据后，就有可能实现更精细化的调度策略——比如对延迟敏感的场景优先使用响应速度快的模型，对成本敏感的场景则选择性价比更高的方案。

二是增强异常检测的自动化程度。目前的异常发现还比较依赖人工巡检看板，后续计划引入基于时序数据的自动异常检测和告警机制，将发现问题的时效从"小时级"缩短到"分钟级"。

三是深化 Trace 数据的利用。完整的调用链数据不仅用于排障，也是评估 Agent 效果、优化 prompt 策略的重要素材。如何从海量 Trace 中提取有价值的模式，是一个值得深入探索的课题。

建设可观测体系的根本目的，是让 Agent 的运行从不透明走向可量化、可治理。这件事没有终点，但每一步都会让系统的可控性上一个台阶。