telemetry-analyzer

用途：分析 watsonx Orchestrate 智能体的遥测 trace，定位 bug 并给出修复建议。可从本地或远程环境导出 trace，也能直接读取磁盘上的 OTel JSON 或 Langfuse 格式 JSON。\n\n主要能力：识别 trace 来源（远程 wxO Traces API、agentops-v3 REST API，本地 IBM 遥测，或已有 JSON 文件）；按 agent 名称或 ID 发现并分页下载 trace；先检测 JSON 格式（OTel 顶层键 traceData.resourceSpans，Langfuse 顶层键 observations），再归一化 span；检测硬错误、LLM 失败（finish_reason 为 length、空输出、零输出 token）、工具调用失败（空 ToolMessage、重试循环、超 30000ms）、agent 逻辑 bug、流程问题、token 异常（累计超 50000、输入输出比过高）和缓存效率。输出 3 个以上问题时生成 HTML 缺陷报告，含执行摘要、trace 汇总表、关键问题、警告、观察和修复建议；单条 trace 直接生成按 thread 的对话流报告。\n\n使用方式：先确保 scripts/ 下存在 search_traces_adk.py、export_traces_adk.py、search_traces_agentops_v3.py、export_traces_agentops_v3.py；确认 trace 来源与时间窗口。远程环境先试 agentops-v3，失败或无结果再回退 ADK；本地用 --with-ibm-telemetry 启动的服务走 ADK 脚本，Traces API 为 http://localhost:4321。常用命令：orchestrate env activate <env-name>；python scripts/search_traces_agentops_v3.py --last 20m 或 --start/--end 加 --all --save-ids data/trace_ids.txt；python scripts/export_traces_agentops_v3.py --ids-file data/trace_ids.txt；本地用 python scripts/search_traces_adk.py --agent-name "My Agent" --last 30m --all --save-ids data/trace_ids.txt 再导出。输出与脚本统一放 data/ 和 scripts/。\n\n适用场景：调试行为异常或返回空的 agent、追踪 token 用量与上下文溢出、排查工具失败与重试、批量分析 trace、重建多轮对话。限制：需先完成 ADK 安装与 .env 配置；本地环境不支持 agentops-v3；具体依赖、权限与收费信息暂未提供。