SuperAPI AI 工具集

agent-telemetry

智能体与模型

查看项目

更新于 10-16 08:03

技能介绍

用途:让编码代理能够查询应用运行时的真实行为。它的出发点是代理在调试时常常无法回答“运行时到底发生了什么”,原因包括日志不存在或只是无结构的 console.log、日志存在但没有给代理查询的途径、代理文档(CLAUDE.md、AGENTS.md)未说明如何访问遥测。

工作流程分五个阶段。第一阶段审计现状:查找日志框架配置(如 winston、pino、bunyan、log4j、slog 等)与日志环境变量(LOG_LEVEL、LOG_FORMAT、OTEL_、SENTRY_DSN),查找 health、metrics、debug、status 等端点,并检查代理文档是否提到日志,据此分类进入后续阶段。第二阶段添加结构化日志:使用结构化 JSON 而非字符串插值,加入关联 ID,在请求/响应中间件、错误处理、外部调用与业务决策点记录,统一字段(timestamp、level、message、requestId、userId、duration、error);最小可用方案是请求日志中间件,记录 timestamp、level、requestId、method、path、statusCode、duration、userId。第三阶段向代理暴露日志,三选一:写日志文件供代理直接读取并用 tail、grep、jq 过滤;开发专用日志端点(推荐 Web 应用),如 GET /__dev/logs?level=error&last=50,仅开发环境可用、返回 JSON、支持按 level、path、时间、requestId 过滤并限制条数;或包装成 CLI 查询脚本。第四阶段在代理文档中记录调试方法,给出可复制命令、日志 schema 与常见调试工作流。第五阶段验证完整闭环。

限制与注意事项:不记录敏感数据,避免只把日志放在云控制台,避免全量 debug 日志,避免缺少请求关联,文档不能只写“查看日志”而无具体命令。官网未提供具体框架实现细节、安装命令或收费信息。