Hermes Agent添加操作日志 Hermes Agent日志系统详解

如果您希望在Hermes Agent运行过程中追踪其执行动作、命令调用与状态变更，则需为其配置可持久化、结构化的操作日志记录机制。

日志配置方法

全局日志配置

在run_agent.py文件中，我们可以看到全局日志配置的示例：

logging.basicConfig(

level=logging.DEBUG,

format="%(ascTIMe)s - %(name)s - %(levelname)s - %(message)s"

)

# 控制第三方库日志级别

logging.getLogger('openai').setLevel(logging.WARNING)

logging.getLogger('httpx').setLevel(logging.WARNING)

Python

运行

这段代码将全局日志级别设置为DEBUG，同时降低了第三方库的日志级别，以减少不必要的日志输出。

工具特定日志配置

Hermes Agent的各个工具模块还支持单独的调试日志配置。例如，在web_tools.py中，我们可以看到：

_debug = DebugSession("web_tools", env_var="WEB_TOOLS_DEBUG")

python

运行

通过设置环境变量WEB_TOOLS_DEBUG=true，可以启用web工具的详细调试日志。类似地，其他工具如image_generation_tool、vision_tools等也都支持类似的环境变量控制。

日志级别使用指南

DEBUG级别

DEBUG级别用于输出详细的调试信息，通常在开发阶段使用。例如，在model_tools.py中：

logger.debug("Could not import %s: %s", mod_name, e)

python

运行

这段代码在导入模块失败时输出DEBUG级别的日志，帮助开发者定位导入问题。

INFO级别

INFO级别用于输出程序运行的关键信息。例如，在environments/hermes_base_env.py中：

("Resolved %d tools for group: %s", len(valid_names), sorted(valid_names))

python

运行

这段代码记录了工具解析的结果，帮助开发者了解系统加载的工具情况。

WARNING级别

WARNING级别用于输出可能存在问题但不影响程序运行的警告信息。例如，在trajectory_compressor.py中：

self.logger.warning(f"Summarization attempt {attempt + 1} failed: {e}")

python

运行

这段代码记录了摘要生成失败的警告，提示开发者可能需要关注摘要功能。

ERROR级别

ERROR级别用于输出影响程序功能的错误信息。例如，在environments/benchmarks/terminalbench_2/terminalbench2_env.py中：

logger.error("Task %s: rollout failed: %s", task_name, e, exc_info=True)

python

运行

这段代码记录了任务执行失败的错误信息，并包含了异常堆栈，帮助开发者定位问题根源。

实用调试技巧

临时调整日志级别

在batch_runner.py中，我们可以看到一个临时调整日志级别的技巧：

# 临时抑制DEBUG日志以避免进度条干扰

root_logger = logging.getLogger()

original_level = root_logger.level

root_logger.setLevel(logging.WARNING)

# 执行某些操作...

root_logger.setLevel(original_level)

python

运行

这种方法可以在不修改全局配置的情况下，临时调整特定代码块的日志级别。

第三方库日志控制

Hermes Agent还提供了控制第三方库日志的方法，在run_agent.py中：

# 降低第三方库日志级别以减少噪音

logging.getLogger('openai').setLevel(logging.WARNING)

logging.getLogger('httpx').setLevel(logging.WARNING)

logging.getLogger('asyncio').setLevel(logging.WARNING)

python

运行

通过这种方式，可以避免第三方库的日志淹没应用程序本身的日志信息。

工具特定调试模式

如前所述，许多工具模块支持通过环境变量启用调试模式。例如，要启用web工具的调试模式，可以执行：

export WEB_TOOLS_DEBUG=true

bash

启用后，相关工具会输出更详细的调试信息，帮助定位问题。

日志分析与问题排查流程

确定日志级别：根据问题严重程度选择合适的日志级别，一般问题排查建议使用INFO或DEBUG级别。

检查关键日志文件：重点关注以下文件中的日志输出：

run_agent.py：主程序运行日志

trajectory_compressor.py：轨迹压缩相关日志

environments/hermes_base_env.py：环境相关日志

具体工具模块日志(如web_tools.py、terminal_tool.py等)

搜索关键词：使用日志分析工具搜索关键词，如"ERROR"、"WARNING"或具体错误信息。

结合上下文分析：日志信息需要结合上下文分析，注意日志中的时间戳和模块名称，以便定位问题发生的位置和原因。

使用调试模式：对于难以定位的问题，可以启用相应工具的调试模式，获取更详细的日志信息。

通过AOP切面统一拦截操作方法

利用Spring AOP对所有继承自BaSeaction的执行方法进行环绕通知，在不侵入业务逻辑的前提下自动记录入参、耗时与结果状态。

1、定义切点表达式@Pointcut("execution(* com.hermes.agent.action..*Action.execute(..))")。

2、在@Around通知中获取方法签名、参数值与执行开始时间。

3、执行目标方法后，捕获返回值或异常，构造包含methodName、params、durationMs、status的JSON字符串。

4、调用info()输出该JSON，并确保日志级别为INFO且独立于普通调试日志。

5、确认切面类已添加@Aspect与@Component注解，并被Spring容器管理。

启用数据库持久化日志表

将高频关键操作(如任务触发、权限校验失败、插件加载异常)写入mysql或PostgreSQL中的t_operation_log表，保障日志不因服务中断而丢失。

1、在数据库中创建表结构，包含字段：id(BIGINT AUTO_INCREMENT)、trace_id(VARCHAR(36))、action_type(VARCHAR(64))、status(TINYINT)、params_json(TEXT)、created_at(DATETIME DEFAULT CURRENT_TIMEStamp)。

2、引入spring-jdbc依赖，在OperationLogService中封装JdbcTemplate.update()插入逻辑。

3、在各核心操作链路末尾(如TaskScheduler.trigger()返回前)调用该服务，传入必要字段。

4、设置数据库连接池最大活跃数不低于5，避免日志写入阻塞主流程。

5、对params_json字段内容执行StringEscapeUtils.escapeJson()处理，防止SQL注入与JSON解析异常。