setting-up-cloudwatch-observability

设置 CloudWatch 可观测性

范围：首次设置 CloudWatch 可观测性，涵盖两款产品——从创建 CloudWatch Application Observability（Omni）Space 到开始接收首批 Trace，以及将服务接入经典 CloudWatch Application Signals。如需使用已设置好的功能（查询、仪表板、警报、Omni 告警、评估、实时调试），请转至 aws-observability。

两款产品，两个参考目录

本技能负责设置两款产品。它们名称中都带有 CloudWatch，但属于不同的服务。参考资料所在的目录表明它属于哪款产品——aws-observability 也采用相同约定：

目录	产品	此处的设置含义
references/cloudwatch-omni/	CloudWatch Omni（Application / Agent Observability）	Domain → Space → 授权 → 接入遥测数据 → 使用原生 ADOT SDK 进行插桩。不使用附加组件、不配置 CloudWatch Agent application_signals，也不使用端口 4316。
references/cloudwatch/	经典 CloudWatch	将服务接入 Application Signals：ADOT 自动插桩、amazon-cloudwatch-observability EKS 附加组件、CloudWatch Agent、受监控服务、ServiceEvents、CI/CD git/部署元数据、端口 4316。

对于同一个工作负载，这两种插桩路径互斥——Omni 路径明确禁止使用 Application Signals 环境变量和附加组件，反之亦然。先确定产品（参见下方路由规则 1–4），然后始终使用对应的目录。启用其中一种不会取代另一种；同一个账户可以在不同服务上同时运行两者。

搭配 AWS MCP 服务使用效果最佳，可直接运行 AWS CLI 命令。所有指南也适用于标准 AWS CLI 访问（Omni 路径使用 aws cloudwatchomni ...；Application Signals 路径使用 aws eks、aws iam 和 aws application-signals）。

概念 — Omni（references/cloudwatch-omni/）

这些是 Omni 的资源。Application Signals 路径中不存在这些资源——该路径没有 Domain、Space、授权或 Dataset；其基本单位是受监控服务，访问控制采用常规 IAM。不要向正在接入 Application Signals 的客户询问 spaceId。

术语	含义
Domain	身份边界。承载授权提供方（IAM 或 Identity Center），并拥有客户访问 Omni 所使用的端点 URL。每个账户一个，或由整个 AWS Organization 共享一个。
Space	存放遥测数据的工作区，且仅属于一个账户和一个 Region。在 Domain 下创建。每个账户每个 Region 最多一个。Region 规则：在仅使用 IAM 的 Domain 下，Space 可以位于与 Domain 不同的 Region；在 Identity Center Domain 下，Space 必须位于 Domain 所在的 Region——如果 Identity Center 配合多个 Region 中的 Space 使用，则需要组织级 Domain。
访问授权	将主体（个人、群组、IAM 身份或异步工作负载）以特定权限级别关联到一个 Space。它是任何人通过 Space 访问数据的唯一方式——但不会限制源 CloudWatch 日志组的访问权限；这些日志组仍由各自的 IAM 权限控制。
访问配置文件	为无需人员参与的异步工作负载（告警、集成、Agent）划定命名边界。它只是一个命名容器：create-access-profile 只接受 Space、名称和描述，不接受其他内容——没有权限、操作或范围参数。只有在分别配置了两组授权（配置文件允许执行的操作；哪些工作负载可以使用该配置文件）并由工作负载指定该配置文件后，它才会发挥作用。
Dataset	查询所针对的数据集。遥测数据通过 CloudWatch OTLP 端点接入，也可以通过转发现有 CloudWatch 日志组中的数据接入。
Omni 从零开始的设置顺序：域 → Space → 授权 → 接入遥测数据 → 埋点。（Application Signals 的步骤要短得多，也不需要前置资源——添加组件/Agent、配置 IAM，然后进行各平台对应的启用更改；请参阅 references/cloudwatch/application-signals-onboarding.md。）“接入遥测数据”（由采集器向 CloudWatch 的 OTLP 端点导出数据，并转发 CloudWatch 中已有数据集）是独立步骤，与工作负载埋点分开。访问配置文件是有条件才需要的，不是流程中的固定步骤——仅当涉及异步工作负载（告警、集成、Agent）时才需要。每次给出此顺序时，也要说明：在 Space 创建之前就开始埋点或转发，操作看起来会成功，但遥测数据并未送达客户可见的位置——先查看 Omni 的客户会把一个正常运行但内容为空的 Space 误认为故障。有关概念间的关系和完整流程，请参阅 references/cloudwatch-omni/app-basics.md。

这是一项路由技能。对用户的设置请求进行分类，并委派给正确的参考文档。Omni 参考文档位于 references/cloudwatch-omni/ 下；经典 CloudWatch（Application Signals）参考文档位于 references/cloudwatch/ 下。

用户意图	参考文档
将服务接入 Application Signals（自动检测、amazon-cloudwatch-observability EKS 附加组件、CloudWatch Agent IAM、受监控服务、遥测数据上报、ServiceEvents、两个接入层级）	references/cloudwatch/application-signals-onboarding.md
通过 CI/CD 传播 ServiceEvents 的 Git／部署元数据（5 个 OTEL_AWS_SERVICE_EVENTS_* 变量、各提供商的模式）	references/cloudwatch/application-signals-cicd-metadata.md
已知平台和语言后，查看各平台 × 各语言的 Application Signals 启用步骤	对应的 references/cloudwatch/appsignals-guides/<platform>-<language>.md（例如 references/cloudwatch/appsignals-guides/eks-python.md）
在接入服务时为其启用 Dynamic Instrumentation（OTEL_AWS_DYNAMIC_INSTRUMENTATION_* 变量及其 IAM）	references/cloudwatch/application-signals-onboarding.md（步骤 5d）。使用该功能进行调试，请参阅 aws-observability
了解 Omni 是什么、其概念或从何处开始	references/cloudwatch-omni/app-basics.md
检测 AI Agent（ADOT、OpenInference、框架检测、跟踪验证），或将 Agent 部署到生产环境并让跟踪数据流入 CloudWatch — 各平台的环境变量（AgentCore、Lambda 或其他平台，如 ECS／EC2／EKS）、将 Span 路由到自定义跟踪日志组、所需的 IAM 权限、ADOT 版本要求	references/cloudwatch-omni/omni-agents-instrumentation/omni-agents-instrumentation.md（部署场景请参阅 § Production deployment）
已知 Agent 框架后，查看各框架的 OpenInference 指南（LangChain、LangGraph、Strands、CrewAI、OpenAI Agents、Vercel AI）	references/cloudwatch-omni/omni-agents-instrumentation/openinference-framework-guide.md，然后查看对应的 references/cloudwatch-omni/omni-agents-instrumentation/instrument-<framework>.md
检测应用程序（在 EC2／ECS／EKS／Lambda 上使用 ADOT SDK — Python、Node.js、Java、.NET）	references/cloudwatch-omni/instrumentation/instrumentation.md
发出自定义应用程序或 Agent 指标，使其可在 Omni 中查询（为何使用 OTLP，而非 PutMetricData／EMF）	references/cloudwatch-omni/instrumentation/instrumentation.md（§ Custom metrics）
创建账户级 Space 或 Domain	references/cloudwatch-omni/spaces-and-domains.md
Space 是否可以与 Domain 位于不同的区域	references/cloudwatch-omni/spaces-and-domains.md（Prerequisites → Region rules）
create-space 要求提供的 AgentCore evaluation role — 它是什么、是否需要创建	references/cloudwatch-omni/spaces-and-domains.md（步骤 3 → Also resolve the AgentCore evaluation role）
已成功创建但使用时返回授权错误的 Space	references/cloudwatch-omni/spaces-and-domains.md（Troubleshooting → If the Space was created but cannot be used）— 这是 Space 访问角色的信任策略问题，而非授权问题
创建在 AWS Organization 中共享的 Domain	references/cloudwatch-omni/org-domains.md
为人员、IAM 身份或警报配置访问授权	references/cloudwatch-omni/access-grants.md
使用 Access Profile 限定警报、集成或 Agent	references/cloudwatch-omni/access-profiles.md
部署 OTel Collector，为检测过的应用提供遥测导出目标（EC2／ECS／EKS）— Collector 将数据导出到 CloudWatch 自有的各信号 OTLP 端点	references/cloudwatch-omni/instrumentation/collector.md
启用 Transaction Search，让跟踪数据进入 Space（仅在启用后，Span 才会写入 aws/spans — 按账户、按区域启用）	references/cloudwatch-omni/instrumentation/collector.md（步骤 1）
将 CloudWatch 中已有的遥测数据转发到 Dataset	references/cloudwatch-omni/data-forwarding-and-centralization.md
从 Azure 发送应用程序自身的遥测数据（服务发出的日志／指标／跟踪数据，通过 Azure VM／AKS 上的 CloudWatch Agent 发送）	references/cloudwatch-omni/azure-ingestion/azure-ingestion.md（意图判定），然后参阅 references/cloudwatch-omni/azure-ingestion/custom-telemetry.md（CloudWatch Agent 在 VM／AKS 上的操作流程）
首次将 Slack 连接到 Space	references/cloudwatch-omni/slack-integration.md
是否可以注册自定义 MCP 工具服务（Omni 不支持）	references/cloudwatch-omni/custom-mcp-integration.md

Routing Rules

1. 如果用户询问 Omni 是什么、Domain、Space 或 grant 的含义、从哪里开始，或从零开始的端到端步骤顺序，而不是要求执行某个单独的设置步骤，请转到 references/cloudwatch-omni/app-basics.md，并按照其中的 “Setup order” 部分说明步骤顺序（不要使用只涵盖单个步骤的 collector.md 等单个操作文件）。该文件还说明了与 aws-observability 的边界。关于某个概念具体规则的问题，例如 Space 的 Region 与其 Domain 的关系、create-space 需要哪些角色，应转到该概念对应的操作文件（spaces-and-domains.md），路由表中对此有说明。
2. 如果请求涉及为 AI Agent 项目添加监控埋点（为 LangChain、LangGraph、Strands、CrewAI、OpenAI Agents 或 Vercel AI 等框架添加 OTel），这属于 Omni——请转到 references/cloudwatch-omni/omni-agents-instrumentation/omni-agents-instrumentation.md。AI Agent 框架没有 Application Signals 路径。
3. 如果请求涉及为通用应用添加监控埋点（EC2、ECS、EKS 或 Lambda 上使用 Python、Node.js、Java 或 .NET 的服务，不包括 AI Agent 框架），打开任何操作文件之前先确定产品——同一个工作负载只能选择以下两条路径之一：
   • 提到 Application Signals、ServiceEvents、“monitored service”、服务映射、amazon-cloudwatch-observability 附加组件、CloudWatch Agent 或端口 4316 → CloudWatch 路径：references/cloudwatch/application-signals-onboarding.md，然后是匹配的平台和语言指南 references/cloudwatch/appsignals-guides/<platform>-<language>.md。
   • 提到 Omni、Application Observability、Space、Domain 或 Dataset，或者明确排除 Application Signals（“纯 OTel”、“不使用附加组件”、“不使用 Agent sidecar”）→ Omni 路径：references/cloudwatch-omni/instrumentation/instrumentation.md。
   • 两者都没提到 → 参阅规则 4。
4. 如果有关监控埋点、ADOT 或 Collector 的请求没有提及任何一种产品（既未提到 Omni 或 Space，也未提到 Application Signals、ServiceEvents 或 amazon-cloudwatch-observability 附加组件），请先检查目标 Region 中是否有 Space，再决定路径。list-spaces 是账户全局命令：--region 标志只用于选择端点，响应会列出账户中的所有 Space，每个 Space 都有自己的 region，因此应筛选目标 Region，不要仅凭列表非空就做判断：aws cloudwatchomni list-spaces --region <region> --query "items[?region=='<region>']"。该 Region 中有 Space → Omni 路径：references/cloudwatch-omni/instrumentation/instrumentation.md。筛选结果为空 → 客户尚未在该 Region 采用 Omni，因此他们目前使用的产品是 Application Signals：references/cloudwatch/application-signals-onboarding.md。无论哪种情况，请求都仍由此技能处理——检查结果只决定使用哪个文件夹，不决定使用哪个技能。如果检查因服务未知而报错，这说明 CLI 模型有问题，并不能证明 Omni 不可用——请根据客户的措辞选择路径；若仍无法确定，再提问。
5. 如果请求涉及 Space/Domain 的创建或配置，请转到对应的设置参考资料。刚创建的 Space 一经使用就出现授权错误，也属于此类问题——这是 Space 访问角色的信任策略问题（create-space 从不会验证是否能代入该角色），因此请转到 references/cloudwatch-omni/spaces-and-domains.md → “If the Space was created but cannot be used”，不要转到访问授权参考资料。
6. 如果用户询问如何将遥测数据发送到某个目标——遥测数据尚未到达 CloudWatch——请在 EC2/ECS/EKS 上部署 OTel Collector，让已添加监控埋点的工作负载有地方发送 OTLP，并将应用的 OTEL_EXPORTER_OTLP_ENDPOINT 指向该 Collector：references/cloudwatch-omni/instrumentation/collector.md。Collector 会直接将数据导出到 CloudWatch 自有的、按信号类型划分的 OTLP 端点。如果遥测数据已经位于 CloudWatch 日志组中，需要转发到 Dataset，请转到 references/cloudwatch-omni/data-forwarding-and-centralization.md。Collector 的 OTLP 导出和 CloudWatch 的 OTLP 端点都使用 SigV4（AWS 凭证）进行身份验证，也包括 AWS 外部工作负载使用的 OIDC 联合凭证（参阅 references/cloudwatch-omni/azure-ingestion/custom-telemetry.md）。对于完全无法获取 AWS 凭证的发送方，基于令牌的摄取路径不在这些技能的涵盖范围内；不要自行编造方案，并应明确说明这一点。
7. 如果请求涉及将 Azure 遥测数据接入 CloudWatch，请转到 references/cloudwatch-omni/azure-ingestion/azure-ingestion.md，并根据意图判断。如果客户想要的是其自有应用产生的遥测数据（其代码生成的日志、指标和跟踪），可通过 Azure VM 或 AKS 集群上的 CloudWatch Agent 实现支持——请遵循参考资料。如果客户想要的是 Azure 资源自行发出的遥测数据（相当于 AWS VPC 流日志或 Route 53 日志），则目前不支持——请明确说明，不要尝试设置。
8. 如果用户首次请求连接、启用或授权 Slack 以供某个 Space 使用（包括授予操作员使用权限），请转到 references/cloudwatch-omni/slack-integration.md。Slack 连接完成后的使用方式（向频道发布发现、提及助手或搜索 Slack）需在 Slack 和控制台中进行，不在这些技能的涵盖范围内；将 Slack 用作告警通知目标，则由 aws-observability 的 Omni 告警参考资料涵盖。
9. Application Signals、ServiceEvents 和 Dynamic Instrumentation 都是 CloudWatch 功能，其划分依据是设置与使用，而不是技能。在尚未启用这些功能的服务上启用它们属于设置，应在此处处理，参考 references/cloudwatch/：Application Signals 入门和 ServiceEvents 见 references/cloudwatch/application-signals-onboarding.md（CI/CD 元数据链见 references/cloudwatch/application-signals-cicd-metadata.md）；在添加监控埋点时启用 Dynamic Instrumentation，则见同一文件的步骤 5d。它们绝不能出现在 Omni 监控埋点变更中——Omni 不涵盖这些功能；请按规则 3 区分两条路径。服务开始上报数据后再使用这些功能——查看服务映射、针对 Application Signals 指标配置告警，或使用 Dynamic Instrumentation 设置断点并读取快照——属于日常工作：请停止处理并转到 aws-observability。
10. 如果用户已有可用的 Space，或服务已向 Application Signals 上报数据，并询问查询、仪表板、告警、警报或调查相关问题，请停止处理并转到 aws-observability。
11. 如果用户询问如何注册自己的 MCP 工具服务、连接自定义 MCP 服务或设置 MCP 身份验证：**CloudWatch Omni 不允许客户添加自定义 MCP 服务。**控制台中没有对应页面，且该集成类型未开放给客户使用，因此该请求无法满足。请明确说明并停止处理；不要描述设置流程，也不要提供替代方案。参阅 references/cloudwatch-omni/custom-mcp-integration.md。
12. 如果用户询问如何连接 GitHub、关联 GitHub 组织或代码库，或从源代码丰富应用映射：**CloudWatch Omni 没有 GitHub 集成。**请明确说明并停止处理——不要介绍设置步骤。不要提供替代方案：Application Signals GitHub Action 和 CloudWatch Logs GitHub 审计日志源是独立的 CloudWatch 功能，不能用于将 GitHub 连接到 Omni；自定义 MCP 服务也不是 GitHub 集成。公开文档中出现与 GitHub 相关的功能，并不能证明 Omni 有 GitHub 集成。
13. 如果请求没有提及任何一种产品——例如“为我的 API 添加可观测性”、“我应该如何开始监控工作负载”，但未提及 Omni、Space、Domain 或任何 CloudWatch 功能——不要自行假定用户指的是哪一种。客户想要设置哪种产品是其意图，无法根据账户当前状态判断，因此请以产品对比的方式询问：CloudWatch Omni（应用/Agent 可观测性——Domains、Spaces、grants、Dataset）还是 CloudWatch（日志组、告警、Log Insights、Application Signals）。两种产品都由此处处理，只是参考资料文件夹不同，因此这是询问要设置哪种产品，而不是询问要使用哪个技能，也不是将请求转给 aws-observability 的理由。在同一条消息中说明两者的边界，帮助用户做出选择——关键在于设置与使用的区别：创建或配置 Domain、Space、grant 或 Access Profile；首次打通遥测数据；为 Omni 应用或 Agent 添加监控埋点；以及为服务启用 Application Signals，均属于首次设置，应在此处处理；查询遥测数据、构建仪表板、配置告警或 Omni 警报、调查线上问题，以及使用 Dynamic Instrumentation 调试，则属于日常使用，应由 aws-observability 处理。在用户确认要使用哪种产品之前，不要开始介绍 Domain/Space 创建或 Application Signals 入门步骤；提问后应停止并等待回复。