本文要点
- AgentCore Runtime 调用失败，CloudWatch 里却找不到可用追踪？
- 最快解法：先核对账号、Region、Runtime 和查询时间，再确认 CloudWatch Transaction Search 已启用、AgentCore 资源已配置对应遥测，最后检查日志目的地与权限；若 Agent 不由 Runtime 托管，还要确认应用已配置 OpenTelemetry 埋点。
- 这篇文章适合正在排查 AgentCore Runtime 调用失败、但缺少诊断线索的开发者。
- 也适合负责配置 CloudWatch 日志和追踪的平台工程师，以及要建立可复现生产排障流程的技术负责人。
AgentCore Runtime 调用失败，CloudWatch 里却找不到可用追踪？ 最快解法：先核对账号、Region、Runtime 和查询时间，再确认 CloudWatch Transaction Search 已启用、AgentCore 资源已配置对应遥测，最后检查日志目的地与权限；若 Agent 不由 Runtime 托管，还要确认应用已配置 OpenTelemetry 埋点。
这篇文章适合正在排查 AgentCore Runtime 调用失败、但缺少诊断线索的开发者。 也适合负责配置 CloudWatch 日志和追踪的平台工程师，以及要建立可复现生产排障流程的技术负责人。
先确认是查错位置，还是确实没有数据
“CloudWatch 没数据”不是单一故障。调用失败说明请求没有按预期完成；日志缺失说明运行输出未出现于当前查看的日志组；追踪缺失则可能是 spans 没有启用、没有送达，或尚未进入可查询的位置。这几类问题要分别核验，不能都归因于 CloudWatch 故障。
排查前先记下目标 AWS 账号、Region、Runtime 名称或 ARN、endpoint、请求时间和 session ID。确认你切换到运行该资源的账号与 Region，再按这次调用的时间范围检索；如果资源在一个 Region、控制台却停留在另一个 Region，即使配置正确，也会看起来像“没有数据”。
| 你看到的现象 | 优先核对 | 这项检查能回答什么 |
|---|---|---|
| 调用失败，日志与追踪都没有 | Runtime、账号、Region、endpoint、时间范围 | 是否查的是实际被调用的资源与时间段 |
| 标准日志存在，但没有 spans | Transaction Search、资源追踪配置、spans 目的地 | Runtime 是否产生并送出了追踪数据 |
| 有指标，但没有 Runtime 日志 | 日志类型是否启用、目的地是否为当前查看的日志组 | 指标可见是否被误当成应用日志已开启 |
| 只有自托管 Agent 没有应用追踪 | OpenTelemetry SDK、框架埋点、导出设置 | Agent 代码是否真的生成并导出了 spans |
| 跨账号查不到日志或追踪 | 数据所在账号、查询角色权限、资源策略 | 数据是否在另一账号，或查询身份是否无权读取 |
AgentCore 生成的默认遥测因资源类型而异：Runtime、Memory、Gateway 等资源可提供不同的指标；不能仅凭某类指标可见，就推断日志和 spans 也已启用。可先查看 AgentCore 可观测性的数据类型说明，再按资源类型核对其默认数据与配置要求。
为什么 AgentCore CloudWatch 里有指标，却搜不到 trace？
第一个常见分支是账户级设置。首次使用时，需要在对应账号启用 CloudWatch Transaction Search；这是账户级配置，不是只对某个 Runtime 点一次开关。AWS 文档说明启用后，spans 才能进入供搜索与分析使用的流程；文档提到的等待时间是启用流程的说明，不应当作所有账号、Region 或运行方式都保证按时出数。请按 Transaction Search 启用说明核实当前状态与数据可见条件。
第二个分支是 spans 的目的地。AgentCore 的 spans 可能出现在 Runtime 自身的日志组，也可能位于共享的 aws/spans 日志组；近期创建的 Runtime 与较早创建的 Runtime，其默认目的地行为可能不同。不要只按旧截图或旧脚本里的路径搜索，应对照 Runtime spans 的位置说明与目的地变更记录，并检查该 Runtime 实际使用的设置。
指标可见但 trace 仍然缺失时，应该从哪里查起？ 若标准日志或指标存在、只有 trace 搜不到，先查 Transaction Search 是否启用，再核对当前 Runtime 的 spans 配置与实际目的地；若调用日志、指标、spans 全部缺失，则先回到账号、Region、资源标识和查询时间范围，不要一开始就改应用埋点。
是哪一种资源没有开启对应遥测？
AgentCore Runtime、Memory、Gateway 的数据不能用同一套“都默认开启”的假设处理。Runtime 可提供服务侧的运行指标；应用日志、资源使用日志及 spans 是否出现，还要看对应日志类型、追踪设置和目的地。Memory 与 Gateway 也有各自的指标和追踪启用要求。按目标资源查看 遥测配置文档，不要把一个资源的启用步骤直接套到另一个资源上。
| 资源或数据类型 | 排查重点 | 常见误判 |
|---|---|---|
| Runtime 指标 | 检查目标 Runtime、Region 与 CloudWatch 指标命名空间 | 有调用指标，就认为应用日志和 spans 已开启 |
| Runtime 应用日志 | 确认应用日志类型与目的地配置，再查 Runtime 对应日志组 | 只搜索共享 aws/spans，漏掉 Runtime 自身日志组 |
| Runtime spans | 确认追踪配置、Transaction Search 与实际 spans 目的地 | 把 spans 缺失一概归因于运行时崩溃 |
| Memory | 区分默认指标与需单独启用的日志、spans | Memory 指标可见，就认为 Memory 追踪也已开启 |
| Gateway | 分开检查 Gateway 指标、日志和追踪设置 | 把 Gateway 的服务侧数据当成 Agent 应用内部 spans |
运行时标准输出日志与结构化遥测也不是同一类数据。标准日志常用于看启动与应用输出；结构化日志或 spans 则依赖相应的遥测配置。先确定你要找的是哪种数据，再决定该查日志组、指标视图还是 Transaction Search。AgentCore 的可观测性入门指南分别说明了 Runtime 托管 Agent 与非 Runtime 托管 Agent 的配置路径。
按这组条件决定下一步查配置、权限还是埋点
- 若同一 Runtime 的调用指标存在，但 spans 不存在：先核对 Transaction Search、资源级追踪配置和 spans 目的地；只有确认数据应该被写入当前日志组后，再重点查写入策略与执行角色权限。
- 若日志组存在，但这次调用没有对应日志：先确认请求确实命中该 Runtime 和 endpoint，再对照日志类型、筛选时间及 session ID；若日志组本身未创建或没有新流，则核对资源日志配置和目的地。
- 若页面报拒绝访问，或你只能看到部分账号的数据：核对当前查询身份的读取权限、日志组所在账号，以及跨账号访问所需的资源策略。避免为了排障直接给过宽的管理员权限，按 Runtime 权限说明检查所需权限范围。
- 若应用日志与服务指标都有，但 Agent 内部操作没有 spans：确认你使用的是 AgentCore Runtime 托管模式，还是自托管模式；自托管 Agent 不能假定服务会自动替应用框架生成追踪。
- 若配置刚变更：确认变更已作用于实际调用的资源，并留出文档所述的查询等待过程；不要把示例等待时间当作 SLA，也不要用旧时间范围判定新配置无效。
非 Runtime 托管的 Agent：检查应用是否真的发出了 spans
如果 Agent 运行在 Runtime 之外，CloudWatch 不会凭空知道框架内部的模型调用、工具调用和业务步骤。按官方自托管 Agent 可观测性步骤检查：项目是否引入并初始化 OpenTelemetry 或 ADOT，所用 Agent 框架是否启用对应的自动埋点，以及 exporter 的目标、Region、服务名和日志组配置是否一致。某些框架还需单独启用框架集成；仅安装 SDK 不等于已经产生 spans。
用同一份安全测试请求做本地与云端对照：本地确认框架能生成 trace，再对照云端的服务名、资源属性、导出目的地和错误输出。若本地也没有 spans，优先修应用埋点；若本地产生而云端没有，重点检查凭证、Region、导出设置与网络访问。对 Runtime 托管 Agent，则先按 Runtime 配置排查，不要把自托管教程中的环境变量照搬过去。
注意：Runtime 应用日志可能包含请求载荷。测试输入若带有个人信息、凭证或客户内容，开启载荷日志前先做脱敏与访问控制；排障记录尽量保留 request ID、session ID 和错误类型，而不是复制完整业务载荷。相关字段行为见 Runtime 遥测数据说明。
用同一份复现记录避免反复猜测
每次排查至少记录：账号与 Region、Runtime 与 endpoint 标识、请求时间及查询时区、session ID 或 request ID、调用是否失败、可见的指标与日志类型、Transaction Search 状态、spans 目标日志组、执行角色与查询身份、最近一次配置变更，以及同一请求在本地是否产生 spans。载荷使用脱敏样本；不要把密钥或完整用户输入贴进工单。
需要进一步核对时，先使用只读方式确认 spans 目的地与状态，例如按官方说明检查 GetTraceSegmentDestination 的返回值；执行前确认命令所在的账号与 Region，并按当前文档核实身份权限。Runtime 调用错误、空日志及正确日志组路径可参照 AgentCore Runtime 故障排查文档。
把本地复现与云端遥测分开处理
如果问题来自 AWS 账号、资源配置、日志目的地或 IAM 权限，Mac 环境不会替你修复 CloudWatch 追踪；应先在 AWS 侧完成遥测验证。Mac 的价值在于短期复现本地依赖、比较不同开发环境的埋点行为，或运行需要 macOS 的构建与测试。若你只是临时需要一台 Mac 做这类对照，租赁通常比为一次排障直接购置设备更灵活；但若你的生产 Agent 长期运行在 Linux 云端，Mac 不是运行时替代品，也不能代替云端日志与告警。
先完成上面的账号、配置与权限检查，再判断是否需要本地环境对照。若你的团队还要核实设备使用与服务支持范围，可先查看 kvmboot 帮助中心；如果需要结合现有 Agent 架构确认是否适合短期租用 Mac，再通过 联系 kvmboot说明测试目标与环境约束。