深入 Amazon Bedrock AgentCore Runtime 的可观测性：自动插桩机制、场景实测与自定义 telemetry
内容提要
Amazon Bedrock AgentCore Runtime的可观测性基于OpenTelemetry，但自动插桩依赖aws-opentelemetry-distro。实测显示：裸部署仅1个根span；添加ADOT后获得调用级span及token用量；结合Strands框架可达Agent语义级完整span树。无框架工作流可用OTEL原生API自定义span/metric补全业务语义。跨资源trace拼接依赖ADOT注入trace context，否则各资源独立成树。
延伸解读
自动插桩并非默认开启
AgentCore Runtime 的“自动插桩”并非无条件生效，它依赖代码依赖中包含 aws-opentelemetry-distro，且 observability 开启。打包期 starter toolkit 会检测依赖，若存在则用 opentelemetry-instrument 启动进程，否则仅以普通方式运行。实测中，裸部署只有 1 个根 span，添加 ADOT 后 span 增至 5 个，并出现 token 用量等 GenAI 属性。
ADOT 是跨资源 trace 拼接的关键
跨资源（如 Memory）的 trace 拼接依赖 ADOT 的 botocore instrumentor。它会给所有 boto3 出站调用添加 CLIENT span 并注入 trace context，使资源侧 vended span 挂到同一棵 trace。无 ADOT 时，各资源独立成树，只能靠 session.id 人工关联。框架（如 Strands）负责产生语义层 span，但无 ADOT 时这些 span 因 no-op provider 而丢失。
无框架工作流可自定义 telemetry 补全语义
对于未使用 agentic 框架的 workflow，多次 LLM 调用产生的 chat span 平级匿名，缺乏业务步骤语义。可通过 OTEL 原生 API 创建自定义 span 和 metric，复用 ADOT 已装配的 provider，无需额外配置 exporter。实测中，自定义 span 能自动成为 chat span 的父级，并可在 CloudWatch 中区分业务埋点与自动插桩。
Q&A
Amazon Bedrock AgentCore Runtime 的可观测性是基于什么技术构建的？
Amazon Bedrock AgentCore Runtime 的可观测性构建在 OpenTelemetry (OTEL) 之上，通过 AWS Distro for OpenTelemetry (ADOT) 将 trace、span、metric 和 log 统一汇入 Amazon CloudWatch，并提供 GenAI Observability 专用仪表板。
AgentCore Runtime 的自动插桩需要满足什么条件？
自动插桩需要同时满足两个条件：代码依赖中包含 aws-opentelemetry-distro，且 AgentCore 的 observability 处于开启状态（默认开启）。否则，Runtime 只会产生服务侧注入的根 span，而不会进行进程内的自动插桩。
在 AgentCore Runtime 中，裸部署（无 ADOT 和框架）时能观测到什么？
裸部署时，每次调用只会产生一个根 span（AgentCore.Runtime.Invoke）以及基础的服务侧指标（如 Invocations、Latency 等），但看不到内部步骤和 token 用量。
添加 aws-opentelemetry-distro 后，AgentCore Runtime 的 trace 会发生什么变化？
添加 ADOT 后，Runtime 的入口会变为 opentelemetry-instrument，从而自动插桩生效。trace 中会增加 HTTP server span（如 POST /invocations）和 LLM 调用 span（如 chat <model>），并包含 gen_ai.* 属性和 token 用量。
使用 Strands 框架开发 Agent 时，可观测性有何特点？
使用 Strands 框架时，除了 ADOT 产生的调用级 span 外，还会产生框架原生的 span（如 invoke_agent、execute_tool），这些 span 带有 agent 语义，形成完整的 span 树，实现 Agent 语义级的可观测性。
对于不使用 agentic 开发框架的 workflow，如何自定义 telemetry 来补全业务语义？
可以通过 OpenTelemetry 原生 API 创建自定义 span 和 metric，复用 ADOT 在 Runtime 上已装配好的 TracerProvider 和 MeterProvider。例如，使用 tracer.start_as_current_span 为每个业务步骤创建 span，并添加自定义属性，从而在 CloudWatch 中看到清晰的业务步骤。
跨资源（如 Memory）的 trace 拼接需要什么条件？
跨资源 trace 拼接依赖 ADOT 的 botocore instrumentor。它会给所有 boto3 出站调用添加 CLIENT span 并注入 trace context，使得资源服务端产生的 span 能挂到同一棵 trace 树上。如果没有 ADOT，各资源会各自产生独立的 trace，无法自动拼接。
AgentCore 服务侧 vended span 的产生是否依赖 ADOT 或框架？
不依赖。AgentCore 服务侧 vended span（如根 span）是无条件产生的，只要资源的 traces delivery 配置正常，无论是否安装 ADOT 或使用框架，都会产生。
