Strands Agents 可观测性完全指南：用 OpenTelemetry 实现模型调用与工具执行的全链路追踪

Strands Agents 可观测性完全指南用 OpenTelemetry 实现模型调用与工具执行的全链路追踪【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址: https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdkStrands Agents 是可观测性开箱即用的生产级 AI Agent SDKPython 与 TypeScript 双语言支持。它内嵌 OpenTelemetry 标准无需手动埋点即可自动记录 Agent 全链路轨迹——每一次模型调用、每一次工具执行、每一轮事件循环连同 Token 用量、延迟和错误状态都会变成可查询的 Span让新手也能快速定位 Agent 的“黑盒”问题。为什么 AI Agent 需要全链路追踪普通 Web 应用出问题时看日志、查链路即可。但 AI Agent 的执行过程是循环 决策的模型可能连续调用多次工具、经历多轮推理才给出答案。当 Agent 答非所问或响应超慢时你至少需要回答三个问题它调用了哪些模型每轮用了多少 Token哪个模型最慢它执行了哪些工具哪个工具入参有误、哪个工具超时或报错循环卡在哪里事件循环event loop跑到第几轮出问题的Strands Agents 通过内嵌的遥测模块给出答案Agent 启动时自动创建层级化的 Span 树一次请求就是一条完整的 Trace。核心实现在 strands-py/src/strands/telemetry/ 目录TypeScript 端对应 strands-ts/src/telemetry/。追踪的层级结构一次请求如何被记录Strands 创建的 Trace 是一个四层嵌套结构与 Agent 真实执行流程一一对应层级Span 名称记录内容Agent Spaninvoke_agent 名称用户提问、最终回答、总 Token 用量、累计延迟循环 Spanexecute_event_loop_cycle每一轮思考的起点含 cycle_id模型 Spanchat发送给模型的提示词、模型 ID、输入/输出 Token、首 Token 延迟工具 Spanexecute_tool 工具名工具名称、调用 ID、入参、执行结果、成功/失败状态每个 Span 都携带标准gen_ai.*语义属性例如gen_ai.request.model模型标识gen_ai.usage.input_tokens/gen_ai.usage.output_tokensToken 用量gen_ai.usage.cache_read.input_tokens缓存命中的 Token 数gen_ai.tool.call.id工具调用唯一 IDgen_ai.event.start_time/gen_ai.event.end_time起止时间戳这套属性命名遵循 OpenTelemetry GenAI 语义约定意味着 Jaeger、Grafana、Langfuse、AWS X-Ray 等任何兼容平台都能直接读懂——不用写任何转换代码。Python 端的 Span 创建逻辑见 tracer.pyTypeScript 端等价实现在 tracer.ts。三步开启全链路追踪最快配置方法第 1 步安装 OpenTelemetry 依赖Python 端通过可选依赖安装一行命令pip install strands-agents[otel]TypeScript 端安装 OpenTelemetry 官方包npm install opentelemetry/api opentelemetry/sdk-trace-node opentelemetry/exporter-trace-otlp-http第 2 步两行代码初始化遥测Python 端使用StrandsTelemetry类它会自动创建 TracerProvider 并注册为全局实例from strands.telemetry import StrandsTelemetry telemetry StrandsTelemetry() telemetry.setup_console_exporter() # 开发调试Span 打印到控制台 telemetry.setup_otlp_exporter() # 生产环境Span 发送到 OTLP 端点之后正常创建Agent即可追踪是自动启用的——所有 Agent 调用、模型请求、工具执行都会生成 Span无需改动业务代码。第 3 步通过环境变量指定收集端点# OTLP 收集器地址 export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4318 # 认证请求头 export OTEL_EXPORTER_OTLP_HEADERSkey1value1,key2value2本地开发时用 Docker 拉起一个 Jaeger 即可在浏览器中实时查看 Trace 瀑布图官方步骤见 traces.mdx。 如果你已经配置好全局的 TracerProvider比如公司统一接入可以直接跳过StrandsTelemetrySDK 会自动复用现有配置。不止于追踪指标Metrics同样内置除了 TraceStrands 还自动导出 12 个 OpenTelemetry 指标覆盖运维最关心的维度循环指标事件循环次数、每轮耗时直方图Token 指标输入/输出/缓存读写 Token 用量直方图模型指标整体延迟、首 Token 延迟TTFT工具指标调用次数、成功次数、失败次数、执行时长指标常量定义在 metrics_constants.py采集逻辑见 metrics.py。启用指标只需一行telemetry.setup_meter(enable_console_exporterTrue, enable_otlp_exporterTrue)配合 Trace 里的trace_id你可以在监控系统中把「某次请求耗时 30 秒」直接下钻到「第 3 轮的某个工具执行了 28 秒」这正是全链路追踪的价值所在。进阶技巧采样、自定义属性与敏感数据脱敏高流量场景的采样控制生产环境 QPS 较高时用标准 OpenTelemetry 变量控制采样率降低存储成本export OTEL_TRACES_SAMPLERtraceidratio export OTEL_TRACES_SAMPLER_ARG0.5 # 只上报 50% 的 Trace为 Span 打上业务标签创建 Agent 时传入trace_attributes把用户 ID、会话 ID 等业务字段挂到所有 Span 上方便按维度检索agent Agent( modelglobal.anthropic.claude-sonnet-5, system_promptYou are a helpful assistant, trace_attributes{session.id: abc-1234, user.id: u-001}, )敏感内容脱敏保护用户数据模型输入输出可能包含隐私数据。SDK 提供白名单式脱敏——通过OTEL_SEMCONV_STABILITY_OPT_IN环境变量中的gen_ai_unredacted_attributes列表指定允许明文上报的属性其余敏感内容gen_ai.input.messages、gen_ai.output.messages、gen_ai.system_instructions、工具入参出参统一替换为[REDACTED]。支持*通配前缀如gen_ai.output.*。策略实现见 tracer.py 的 _redact 方法。切换到最新语义约定如果你的后端支持新版 GenAI 语义约定可以一次性开启export OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental,gen_ai_tool_definitions前者更新属性命名并改用统一的事件格式后者会把完整工具定义JSON Schema附加到 Agent Span 上排查“模型为什么选错工具”时非常有用。常见问题速查问题排查方向平台上看不到 Trace检查OTEL_EXPORTER_OTLP_ENDPOINT是否可达确认端口 4318/4317 开放Trace 数据量过大开启采样OTEL_TRACES_SAMPLER或用脱敏策略压缩内容想看控制台输出调试加一行setup_console_exporter()无需任何外部服务Trace 被拆散不连续确认跨服务调用时使用了上下文传播SDK 已内置 W3C 传播器小结Strands Agents 把 OpenTelemetry 的接入成本降到接近于零安装可选依赖、两行初始化代码、一个环境变量模型调用与工具执行的全链路追踪即刻生效。它的层级化 Span 结构忠实还原了 Agent 的循环推理过程内置指标覆盖了 Token 成本与延迟监控再加上采样、业务标签与脱敏能力从本地调试到生产排障都能复用同一套遥测管道。可观测性不是上线前的“补票”而是 Agent 工程的第一课——现在就可以打开你的 Agent 项目把第一行遥测代码加上。【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址: https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考