aws-observability

AWS 可观测性

概述

涵盖 AWS 在指标、日志和追踪方面的可观测性专业知识，适用于两种 产品。它们都使用 CloudWatch 这个名称，但属于独立服务，拥有各自独立的 控制平面、数据模型和 API：

	CloudWatch	CloudWatch Omni
产品定义	日志组、指标命名空间、告警、Log Insights、X-Ray、Application Signals	Application Observability / Agent Observability。每个账户在每个区域都有一个 Space，作为访问该账户 CloudWatch Dataset 的边界（其中包含 OpenTelemetry 日志、追踪和指标）；Dataset 是 Space 读取的 CloudWatch 资源，而不是 Space 所包含的内容
控制平面	aws cloudwatch、aws logs、aws xray、aws application-signals	aws cloudwatchomni（端点前缀 cloudwatch-omni，签名名称 cloudwatch）
查询	Log Insights 查询语言；GetMetricData	对 logs.default / traces.default 使用 SQL；对指标使用 PromQL；命名视图
通知	告警（指标、复合、异常）	警报（SQL/PromQL 规则、贡献者、OK/WARNING/CRITICAL/NODATA）
拓扑	Application Signals 服务映射	上下文图（GetContextGraph）
访问	仅限 IAM	域 → Space → 访问授权和访问配置文件（在 setting-up-cloudwatch-observability 中设置）
仅此产品支持	Dynamic Instrumentation、Synthetics canaries、CloudTrail 审计、EMF	Agent 质量评估、视图、上下文图
首次设置	Application Signals 入门设置 — ADOT 自动检测、amazon-cloudwatch-observability 插件、ServiceEvents、CI/CD 元数据	域 → Space → 授权 → 接入遥测数据 → 纯 ADOT 检测
参考资料	references/cloudwatch/	references/cloudwatch-omni/

此技能涵盖如何使用这两种产品，绝不负责设置其中任何一种。 上述两种首次 设置流程都位于 setting-up-cloudwatch-observability（同样按两个文件夹划分）中； 请转到该技能，而不要凭记忆描述入门流程。

启用 Omni 并不会取代 CloudWatch；日志组、指标和告警仍会继续工作，大多数客户会同时使用两者。

与 AWS MCP 服务 配合效果最佳 — 可直接运行 CLI 命令、查询 CloudWatch 并验证配置。所有指导也适用于标准 AWS CLI 访问方式。

注意： 参考文件包含具体的运行时版本、配额值和功能矩阵，这些内容可能会变动。需要精确 信息时（例如，部署到生产环境、选择运行时或检查配额），请对照当前 AWS 文档确认，而不要 只依赖这些文件中的值。

范围判断 — 这是可观测性请求吗？

此技能负责判断所有路由至此的请求是否在范围内，本节是唯一进行此判断的地方。

如果请求与使用 CloudWatch 或 CloudWatch Omni 的 AWS 可观测性无关 （例如天气、冷知识、一般闲聊、非可观测性编码），请用一句话婉拒：明确说明请求 超出范围，绝不编造答案，也绝不声称自己受到不存在的能力限制（不要说“无法访问互联网” 或“没有天气数据”）——理由只是请求超出范围。然后指出此技能涵盖的内容：查询 CloudWatch 和 CloudWatch Omni 日志、追踪和指标，构建仪表板，配置警报，调查服务，或评估 Agent。

不要尝试完成无关任务，也不要为此调用工具或运行查询。简短作答即可：不说教，不长篇拒绝。

第 0 步 — CloudWatch 还是 CloudWatch Omni？

在路由请求前先做出判断。自然语言表述（“为高延迟设置警报”、“构建仪表板”、 “查询我的日志”）并未说明客户指的是哪种产品。

1. 客户明确指出产品名称——“Omni”、“Application Observability”、“Agent Observability”、Space、Domain、Dataset、访问授权、spaceId、cloudwatch-omni、 Omni SQL、PromQL、视图、上下文图、评估器、Agent 评估／评分轨迹／在线或持续评估／gen_ai.evaluation，以及 OTel span 词汇 （traces.default、logs.default、spans、durationNano、status.code、资源 属性、service.name）→ Omni。“Log Insights”、“日志组”、“指标命名空间”、“CloudWatch 警报”、“指标警报”、“复合警报”、“异常警报”、 “X-Ray”、“Application Signals”、“canary”、“CloudTrail”、“Dynamic Instrumentation”→ CloudWatch。在 Agent 评估请求中提到的“日志组”，是需要验证的在线评估数据源，而不是 CloudWatch 信号。单独出现的“警报”（或“告警”），且没有其他产品信号时，存在歧义——转到规则 3 并进行探查：有 Space → Omni 警报 (alerts.md)；没有 Space → CloudWatch 警报 (cloudwatch/alarms.md)。例外：“PromQL 警报”是针对 OTel 指标的 CloudWatch 警报 (cloudwatch/alarms.md)——“警报”优先于“PromQL”。

2. 知识或操作指南问题（“什么是 Omni 警报”、“Omni 有 API 吗”、“警报和告警有什么区别”）→ 直接根据参考文件作答。不要探查账户，也不要转向另一个产品。某项功能是否存在，是产品本身的事实，而非账户信息。 concepts.md 包含完整的功能对应关系表。 2a. 编写／操作指南类警报请求——“创建／设置／编写一个在 X 条件下触发的 Omni 警报”、“我应该如何针对 Y 设置警报”——未提供 Space 或 Region，且未明确同意实际创建时，属于操作指南请求。首先提供编写指南（下方“必须说明的检查清单”中的警报条目，然后参阅 alerts.md），依据参考文件作答。不要因 Region／Space 不明确而停下来追问，也不要把明确要求“Omni 警报”的请求改为使用 CloudWatch 警报。只有当用户提供 Space／Region 或要求你创建警报后，才探查账户。 2b. 提示中已包含遥测对象——用户粘贴，或 UI 将 span、trace、日志记录或查询结果作为上下文传入，并询问其含义、包含哪些错误或耗时多久。这不是实时数据请求：不要探查账户、运行查询，也不要要求用户再次获取该数据。按照 query/sql-logs-traces.md 中“解读已有的 span 或 trace”部分就地解读，并说明其中“必须说明”清单的每一项。 2c. 实时结果为空或无法访问的查询请求（“显示耗时最长的 spans”、“哪些 traces 失败了”）仍应提供方法——给出准确的查询，以及确保查询正确的字段规则（参见 query/sql-logs-traces.md 中标注的必须说明事项）。零行结果、Space 所在 Region 错误或端点无法访问，都应作为发现与查询一并报告，绝不能作为完整答案。

3. 必须对实时数据执行操作，且措辞有歧义的请求（不是 Step 0.5 中应根据目录作答的内容问题）→ 首先探查目标 Region：

   aws cloudwatchomni list-domains
   aws cloudwatchomni list-spaces --region <target-region> --query "items[?region=='<target-region>']"  # account-global; filter to the Region
   

   • list-spaces 是 账号全局 的（--region 标志仅用于选择端点），因此要像所示那样将其结果过滤到目标 Region，而不能把非空列表当作证据；每个账号在每个 Region 中只有一个 Space。完整的 Region 探测理由见 references/cloudwatch-omni/concepts.md。
   • 该 Region 中有一个 Domain 和一个 Space（过滤后的列表非空）→ Omni。
   • 该 Region 中没有 Space（过滤后的列表为空）→ CloudWatch：告警 → cloudwatch/alarms.md， 仪表板 → cloudwatch/dashboards.md，查询 → cloudwatch/log-insights.md，指标 → cloudwatch/metrics.md。如果客户明确要求使用 Omni 但 没有 Space，那是首次设置——见步骤 4。
   • 探测本身报错（"not yet supported"、未知服务、端点无法 解析）→ 所使用的 CLI/SDK 模型缺少 cloudwatchomni。这 并不 证明 Omni 不存在，绝不能报告为 "Omni is unavailable"。客户 安装的 AWS CLI/SDK 很可能早于该服务。如果请求带有 任何 Omni 信号，请把升级命令交给客户去运行（重新安装 AWS CLI v2 或 brew upgrade awscli；pip install -U boto3 botocore），并让他们 重新运行 aws cloudwatchomni list-domains——确切步骤见 programmatic-access.md。切勿 自行在主机上运行包管理器升级或安装程序（brew、pip install -U、.pkg/MSI）；这会超出请求范围变更客户的机器，且 可能破坏无关的工具——把命令交给客户，然后继续提供指导。 绝不要用 CloudWatch 或 X-Ray 命令替代 Omni 请求。如果请求 带有 没有 Omni 信号，则不要因升级而阻塞。当你已经要 因缺少输入（例如告警的阈值和 周期）回问客户时，在同一个问题中询问他们想要哪个产品：说明 Space 探测在此 CLI 上无法运行，描述两个选项，并在他们回答前两者都不构建。当 请求已完全明确或说明不要询问时，按 CloudWatch 路径继续（ Omni 之前的默认值），并仅顺带提及升级。
   • 仍无法确定 → 询问客户。

4. 首次设置，针对任一产品 → 停止并转至 setting-up-cloudwatch-observability 技能。 本技能针对的是已经在 上报的服务或 Space，且不包含任一产品的入门流程，因此这里没有什么 可以回退：既不是 Omni 设置（创建 Domain 或 Space、授予访问权限、 摄取、转发、Slack、为 Space 埋点应用或 AI Agent），也不是 CloudWatch 设置（将服务入门到 Application Signals——ADOT 自动埋点、amazon-cloudwatch-observability 插件、受监控服务、 ServiceEvents、CI/CD 元数据、各平台的启用指南）。任何 埋点 / ADOT / 收集器请求无论如何都是设置请求；设置技能 也负责产品决策，因此请把整个请求交出去，而不是自行探测 list-spaces。Application Signals 一旦开始上报——服务地图、 基于其指标的告警、Dynamic Instrumentation 调试——则属于此处。

描述不完整的告警请求： 当告警或报警请求指明了要监视的内容（一个 症状或一个服务）但未给出其所需输入——阈值和评估 周期——请询问这些内容，而不是自行编造。通知是可选的（见 alerts.md），因此只有在用户希望收到通知时才询问通知目标。 这在两条路径上都适用（Omni 告警或 CloudWatch 告警）。 信息不充分的仪表板请求： 当仪表板请求指出要显示什么，却没有指定指标、面板或布局时，应结合数据来确定，并确认面板集合，而不是自行编造面板；仪表板没有阈值、周期或通知。对于任何编写或保存仪表板的请求，还要打开 dashboards.md，并展示其中的“构建或保存 Omni 仪表板时必须展示的事实”检查清单（见下文“必须说明的检查清单”）。某类具名资源需要哪些信号或面板，这是 Step 0.5 的目录问题，而不是仪表板文件的问题。

Step 0.5 — 服务健康调查（路由）

许多实际问题会以运维人员遇到的症状来描述，而不是以工具来描述，例如：“我的 <service> 是否被限流／响应缓慢／报错／状态不健康”“我的哪些 <service> 出现了 <symptom>”“我的 <service> 健康状况如何”“<service> 依赖什么，哪个依赖出了问题”“<service> 应关注哪些信号／仪表板或视图上应该展示什么”。这些都是可观测性数据问题。应从遥测数据入手；即使同时获取实时数值，即使账户中不存在匹配的资源，也要根据方法论作答（说明正确的信号、聚合方式、范围界定和注意事项）。 遥测数据反映症状。原因往往是某个已配置的值，因此，如果问题是在问某项功能为什么失败，还要读取相关资源的配置，例如 API Gateway 集成超时、SQS 可见性超时，或 Lambda 超时或事件源映射。只读或“仅日志”角色通常仍可调用这些 Get 和 Describe API。请实际调用；如果发生 AccessDenied，则报告这一情况。

根据症状进行路由，然后打开参考文档，并展示其“必须说明的事实”检查清单中所有适用项——检查清单是输出要求，位于参考文件中，而不在此处：

• 关于某项 AWS 服务指标的症状（限流、延迟、错误率、重启、饱和度、“应关注哪些信号”，某类具名资源在仪表板或视图上需要哪些信号或面板）→ query/promql-metrics.md。 打开其中的**“服务健康问题 — 必须说明的事实”**部分，并展示所有适用项。即使提到仪表板或视图，也不应路由到两个仪表板文件（两者都不包含信号事实），也不应路由到规则 3 的探测——这是一个内容问题。
• “<service> 依赖什么／下游哪里出了问题”／影响范围／谁会受到影响／应该沿图的哪个方向排查／CALLS、ACCESSES、RUNS_ON 分别是什么意思 → context-graph.md。打开其中的**“依赖／影响范围问题 — 必须说明的事实”**部分，并展示所有适用项。如果某个延迟或错误症状是通过图、依赖关系或边类型来描述的，应路由到此处，而不是上面的指标条目。
• 单个缓慢或失败的 Span／Trace（“<service> 最慢的 Span”“哪些 Trace 失败了”）属于 Trace SQL，而不是指标聚合 → query/sql-logs-traces.md。打开其中的**“Span Duration”和“Finding failed spans”**部分，并说明其中所有必须说明的要点——如果问题询问服务的延迟或错误率（聚合信号），则应路由到上面的 PromQL 条目。

必须说明的清单 — 输出约定

有三项 Omni 任务需要在回答文本中包含清单，而不只是计划中提及。请打开参考资料，并列出所有与请求相关的条目；参考资料包含每项的详细信息，是唯一可信来源，因此此处不要重述。

任务	打开	需说明的章节
编写或提供 Omni 告警建议	alerts.md	“编写告警时必须说明的事实”
为追踪评分、选择评估器、读取已存储的分数、在线／持续评估、评估数据集	agent-evaluation.md	所有 “向用户说明以下全部内容” 提示框
编写、保存、读回或调试 Omni 控制面板	dashboards.md	“构建或保存 Omni 控制面板时必须说明的事实”

路由 — CloudWatch（references/cloudwatch/）

用户需求	操作
为服务启用／接入 Application Signals（自动检测、amazon-cloudwatch-observability 插件、受监控服务）、通过 CI/CD 传递 ServiceEvents Git／部署元数据，或按平台 × 语言分类的启用步骤	停止 — 这是 CloudWatch 的首次设置，此处没有涵盖相关内容的参考资料。请转至 setting-up-cloudwatch-observability 技能
编写 Log Insights 查询（管道分隔语法：fields、filter、stats、sort、parse、display）	阅读 log-insights.md。如果 StartQuery 因查询时间范围早于日志组创建时间而拒绝请求，请使用 FilterLogEvents 读取相同时间范围。参阅其中的已知问题 11
配置告警（指标、复合、异常）	阅读 alarms.md。如需处理 Omni 告警，请参阅 Omni 表格
发布自定义指标或使用 EMF	阅读 metrics.md
X-Ray／ADOT 跟踪行为 — X-Ray SDK 与 ADOT 的选择、跟踪和段结构、注释与元数据、采样规则、收集器管道配置、X-Ray→OTel 迁移陷阱	阅读 tracing.md。尚未进行检测的服务接入属于设置技能的工作（参阅第一行）
构建 CloudWatch 控制面板（小组件机制；特定 AWS 服务需要哪些信号属于步骤 0.5）	阅读 dashboards.md
调试可观测性问题	阅读 troubleshooting.md — 从 5 个最常见的修复方法开始
调试 Canary 故障	阅读 synthetics.md — 参阅常见故障表
CloudTrail 运维审计	阅读 cloudtrail.md
使用 CDK 设置 Lambda 监控	使用 alarm-template.ts 作为起点
创建合成 Canary	阅读 synthetics.md
配置 ADOT 收集器	使用 otel-config.yaml 作为起点
使用断点／快照调试正在运行的服务 — 动态检测（会修改运行中的服务并捕获实时数据）	执行前请完整阅读 dynamic-instrumentation.md。创建／删除前请与用户确认，并在重要操作前说明：观察结果 → 假设 → 拟议操作 → 预期结果。仅检查源代码只能找出假设，无法确认根因；在运行时证据证实之前，应将疑似原因视为暂定判断。

路由 — CloudWatch Omni（references/cloudwatch-omni/）

涉及对实时 Space 数据执行操作的行，假定步骤 0 已找到 Space。知识类问题直接依据文件回答。

用户需求	操作
概念。 Omni 是什么，Domain / Space / Dataset / grant / profile / view / alert / context graph 分别是什么，某项功能属于 Omni 还是 CloudWatch，以及从哪里开始设置	阅读 concepts.md
查询日志或跟踪 — SQL（SELECT … FROM logs.default / traces.default / default）、字段访问、架构发现、耗时最长 / 失败的 span（durationNano、status.code）、TABLESAMPLE	阅读 query/sql-logs-traces.md。对于耗时最长或失败的 span，即使实时结果为空，也要说明其「Span Duration」/「Finding failed spans」必需说明框中的每一项
提示词中提供了 span、trace 或日志记录 —「我打开了这个 span，其中有哪些错误？」、粘贴的遥测对象	阅读 query/sql-logs-traces.md 中的 **「Reading a span or trace you already have」**部分。根据对象自身的字段作答；不要探测、查询或要求用户获取该对象
查询指标 — PromQL、针对不同 AWS 服务的症状应使用哪个指标、指标缺失的原因、gauge 与 counter	阅读 query/promql-metrics.md。指标使用 PromQL，绝不使用 SQL
视图 — 创建、管理或查询命名的可复用 SQL（FROM view.<name>）	阅读 query/views.md
Omni 中的控制面板 — 组合面板、为面板查询提供依据、编写 panels[]、布局网格、API 保存语义（根级或面板级键未知、缺少 type / layout，或变体错误，会在保存时被拒绝并返回 400 ValidationException；枚举值错误、x+w>60，或 config 中含未知键，则会以 200 保存，并在渲染时失败或被忽略；保存前请先验证）、修复空面板或白屏面板、*OmniDashboard API	阅读 dashboards.md
Omni 中的告警 — 提及 Omni alert、CreateAlert / GetAlert / ListAlerts / UpdateAlert / DeleteAlert、profileId、告警 ARN，或告警与 alarms 的区别；创建、调优、添加标签、列出、删除；通知	阅读 alerts.md。告警 API 确实存在且是核心功能——不要转而介绍 CloudWatch alarms。对于 Omni 未启用时的 CloudWatch alarms，请阅读 cloudwatch/alarms.md
上下文图 — 服务 X 为什么变慢或发生故障、它依赖什么、上游 / 下游、遍历方向、边类型 CALLS / ACCESSES / RUNS_ON、影响范围、从洞察或异常追溯根因、GetContextGraph	阅读 context-graph.md，并说明其中「facts you MUST surface」部分所有适用的内容
Agent 评估 — 按需为 trace 评分、选择评估器、读取已存储的 gen_ai.evaluation.* 评分（「哪些评估器表现最差」「哪些在线评估器不健康 / 表现不佳」）、根据 trace 构建数据集、设置在线评估、编写自定义评估器、审核 Agent 的 trace 是否正在流入	阅读 agent-evaluation.md，并说明其中「tell the user ALL of this」说明框内所有适用的内容
程序化访问 —「Omni 是否提供 API 或 SDK」、通过代码、CI、IaC 或 AI 编码 Agent 调用 Omni	阅读 programmatic-access.md。Omni 确实提供公开的 SigV4 API；绝不要回答说它没有 API，也不要用 CloudWatch 或 X-Ray CLI / SDK 替代，并且无需探测 Space 即可作答
谁有权访问某个 Space、授予或撤销访问权限、访问 profile、创建 Space 或 Domain、摄取、转发、Slack、Azure、为应用或 AI Agent 添加监测，以及在 CloudWatch 端将服务接入 Application Signals	转到 setting-up-cloudwatch-observability 技能。如果本地未安装，请使用 AWS MCP retrieve_skill 工具加载（skill_name: setting-up-cloudwatch-observability；对于其引用的参考资料，请传入 file）
涉及多个领域	先阅读最具体的参考资料，再按需查阅其他资料

文件

references/cloudwatch/

文件	内容
alarms.md	指标、复合、异常检测告警 — 配置、限制、推荐默认值
log-insights.md	完整的查询语法、命令、函数、已知问题、可复用查询库
metrics.md	自定义指标、EMF 规范、指标筛选器、高分辨率、保留期限
tracing.md	从 X-Ray 迁移到 ADOT、采样规则、注释与元数据的区别、收集器配置
dashboards.md	小组件类型、跨账户/区域、动态标签、共享
troubleshooting.md	所有可观测性服务的错误 → 原因 → 修复方案
cloudtrail.md	运维审计、事件类型、S3+Athena 查询
synthetics.md	Canary 运行时/蓝图限制、VPC 网络、常见故障
dynamic-instrumentation.md	动态插桩调试循环 — 在运行中的代码上设置断点/探针、快照捕获与关联分析、创建/删除门控、快照 PII 处理。通过 scripts/cloudwatch/di_instrumentation.py + scripts/cloudwatch/di_snapshots.py 运行；详情见 dynamic-instrumentation/
alarm-template.ts	Lambda 监控的最佳实践 CDK 模板（告警 + 控制面板）
otel-config.yaml	用于 X-Ray 跟踪 + CloudWatch EMF 指标的 ADOT 收集器配置

此处有意不包含： Application Signals 入门设置（启用流程、ServiceEvents CI/CD 链、16 份按平台划分的指南）属于首次设置内容，位于 setting-up-cloudwatch-observability 中。请勿凭记忆在此重建；应转至该处。

references/cloudwatch-omni/

文件	内容
concepts.md	Omni 是什么、不是什么；术语表（Domain、Space、Dataset、授权、配置文件、视图、告警、控制面板、上下文图、评估器）；Omni 与 CloudWatch 功能等效性对照表；如何判断客户指的是哪种产品；设置顺序及其所在位置
context-graph.md	Omni 根据追踪和指标构建的服务／资源拓扑；GetContextGraph 请求／响应及 CLI；如何解读上游与下游以及影响范围；如何从洞察或异常逐跳追溯到根本原因，然后转向查询
programmatic-access.md	公共 SigV4 API（cloudwatch-omni 端点前缀、cloudwatch 签名名称）、访问授权如何为编程调用者授权、CLI／SDK 访问（以及为什么不支持服务错误是客户端版本问题）、CloudFormation／CDK、AI 编码 Agent，以及应避免的错误答案
query/sql-logs-traces.md	对日志和追踪使用 SQL——表寻址、必需的时间范围、系统字段、字段访问和引号、架构发现、支持的操作、函数、常见模式（包括 durationNano 跨度时长）、限制、TABLESAMPLE
query/promql-metrics.md	Omni 中的指标使用 PromQL——可查询的内容（OTLP、跨度 RED、经 OTel 丰富的托管指标）与不可查询的内容、标签约定、__name__ 匹配器、对计数器使用 rate()、按 AWS 服务划分的指标目录（含推导公式和维度陷阱）
query/views.md	命名 SQL 视图：CreateView / UpdateView / DeleteView / ListViews、FROM view.<name>、命名和定义规则、组合模式
dashboards.md	Omni 控制面板——组合方案、面板查询的数据依据、panels[] 请求体和面板类型、可视化、60 列网格、API 保存语义（未知根级／面板键会被拒绝并返回 400；config 中的未知键会保存并返回 200，但渲染时会被忽略；保存前请先验证）、排查空白／无内容的面板、Create/Get/List/Update/DeleteOmniDashboard API、原型模板
alerts.md	Omni 告警——告警与警报的区别、评估（FIELD_VALUE / COUNT_OF_RESULTS、贡献者）、状态和无数据处理、通知规则、创建／更新／删除／标记／获取的逐步操作，以及告警 API
agent-evaluation.md	基于 OTel 追踪评估 Agent 质量——检测仪表化健康状况、选择评估器、按需评分、在线评估、自定义评估器、根据追踪创建数据集，以及读取已存储的 gen_ai.evaluation.* 评分（检索计划 + SQL 机制）。使用 scripts/cloudwatch-omni/evaluate_traces.py 和 scripts/cloudwatch-omni/capture_dataset_from_traces.py