View a markdown version of this page

监控服务事件 - Amazon CloudWatch
服务事件的工作原理数据存储在控制台中查看错误在日志中查看服务事件CloudWatch Application Signals MCP（模型上下文协议）服务器中的服务事件配置服务事件配置部署事件
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

监控服务事件

利用服务事件可自动深度观察通过 CloudWatch Application Signals 监控的服务。它会捕获错误指标、函数级性能数据、事件快照（当请求超过延迟阈值或引发异常时）和部署事件，而无需额外的代码更改。

服务事件的工作原理

服务事件会从检测的服务中收集以下类型的信号：

  • 错误指标：每项操作的每种异常类型的错误计数和比率，使您能够识别哪些异常最频繁且呈上升趋势。

  • 函数调用指标：应用程序代码中各个函数的调用计数、持续时间和错误率。

  • 事件快照：当请求超过延迟阈值或引发异常时触发的详细捕获，包括堆栈跟踪、调用树、调用者详细信息和操作上下文。

  • 部署事件：应用程序启动时和每 24 小时发出的标记，可将代码部署与服务行为的变化相关联。应用程序会自动发出部署事件。提供部署元数据（git commit、部署 ID）可为这些事件提供更多上下文。

当为服务启用 CloudWatch Application Signals 时，服务事件会自动启用。错误指标和异常跟踪将立即生效。函数调用指标需要其他配置：在收集函数调用数据之前必须配置要检测的程序包（请参阅 启用函数检测）。可以通过设置 OTEL_AWS_SERVICE_EVENTS_ENABLED=false 来禁用服务事件。数据从 ADOT SDK 流向 CloudWatch 代理。代理会将事件发布到 CloudWatch Logs（/aws/service-events/service-name 日志组）和 CloudWatch 指标。

支持的语言：Java、Python 和 Node.js。

注意

Lambda 环境中会自动禁用服务事件。

数据存储

服务事件会将数据存储在 CloudWatch Logs 中。CloudWatch 会将服务事件数据发布到前缀为 /aws/application-signals/service-name 的日志组，其中 service-name 是您的 OTEL_SERVICE_NAME 环境变量的值。每个服务可创建一个日志组。

日志摄取和存储费用按标准 CloudWatch Logs 费率收取。

在控制台中查看错误

在 CloudWatch 控制台中，导航到 Application Signals，选择服务，然后选择错误选项卡。此选项卡会显示服务的异常指标。

该选项卡显示：

  • 异常计数图表，显示错误随时间变化的趋势。使用它可以检测哪些异常类型的频率最近发生了变化。

  • 一个表格，列出每种异常类型、发生异常的操作、发生次数以及与上一时期相比的变化。

选择一个异常可深入了解详细信息，包括堆栈跟踪、异常消息以及指向关联跟踪的链接。

错误按操作、异常类型和顶级堆栈帧进行分组。仅显示每个组的最新代表。

注意

要查看错误数据，账户中必须至少存在一个 /aws/service-events/service-name 日志组。如果不存在日志组，则“错误”选项卡会显示引导提示。

在日志中查看服务事件

服务事件数据存储在 CloudWatch Logs 中前缀为 /aws/service-events/service-name 的日志组下。您可以使用 CloudWatch Logs Insights 直接查询此数据，以构建自定义视图、创建控制面板或调查特定事件。

要查询服务事件，请执行下面的操作：

  1. 打开 CloudWatch 控制台并导航至 Logs Insights。

  2. 为服务选择日志组 /aws/service-events/service-name。

  3. 输入一个查询以筛选和分析服务事件数据。

CloudWatch Application Signals MCP（模型上下文协议）服务器中的服务事件

服务事件数据可通过 CloudWatch Application Signals MCP（模型上下文协议）服务器访问，从而使人工智能编码助手和代理能够直接查询服务的运行时行为。

故障排查

  • 自动将代码中的错误与生产事件快照相关联，包括完整的堆栈跟踪和受影响的端点。

  • 使用事件上下文（异常类型、调用路径、跟踪 ID）提出有针对性的修复建议，而无需手动导航控制面板。

  • 检索部署事件，以确定最新版本是否引入了回归。

性能改进

  • 在调查延迟问题时查询函数级性能数据以识别瓶颈。

  • 比较不同部署的函数调用持续时间以查明性能回归情况。

有关设置和使用说明，请参阅 GitHub 网站上的 Application Signals MCP 服务器。

配置服务事件

先决条件

要使用服务事件，请确保您拥有下列组件所需的最低版本：

  1. 更新 ADOT SDK：将适用于您的语言（Java、Python 或 Node.js）的 Amazon Distro for OpenTelemetry（ADOT）检测 SDK 更新到最新版本。

  2. 更新 Amazon EKS 附加组件（若适用）：如果使用 CloudWatch Observability Amazon EKS 附加组件来检测应用程序，请更新到该附加组件的最新版本。

  3. 更新 CloudWatch 代理：更新到 CloudWatch 代理的版本 1.300069.0 或更高版本。

如果使用 Amazon EKS，请参阅 在 Amazon EKS 集群上启用应用程序，了解附加组件设置说明。

默认启用的功能

如果使用 CloudWatch Application Signals，则会默认启用以下服务事件信号，无需额外配置：

  • 事件快照（在发生异常和延迟阈值违规时触发）

  • 错误指标（每项操作的每种异常类型的错误计数）

  • 部署事件（始终发出；提供部署元数据时会进行丰富）

  • 函数检测（默认启用，但只有在配置要检测的程序包后才会生成指标）

以下功能是选择加入的，需要设置环境变量才能生成数据：

  • 函数级指标（需要配置 OTEL_AWS_SERVICE_EVENTS_PACKAGES_INCLUDE）

  • 自定义端点筛选

  • 每个端点的延迟阈值

常规设置

环境变量 默认值 说明
OTEL_AWS_SERVICE_EVENTS_ENABLED 遵循 CloudWatch Application Signals 切换服务事件。启用 CloudWatch Application Signals 时，服务事件会自动启用。设置为 false 以显式禁用。
OTEL_AWS_SERVICE_EVENTS_SAMPLING_MODE always 控制函数调用数据采样策略。值：always（记录所有函数调用）、auto（让 SDK 根据负载决定）、never（禁用函数调用记录）。仅当配置了函数检测程序包时适用。

启用函数检测

函数检测默认启用，但只有在配置要检测的程序包之后才会生成指标。提供一个程序包允许列表，以开始收集每个函数的遥测数据：

环境变量 默认值 说明
OTEL_AWS_SERVICE_EVENTS_FUNCTION_INSTRUMENT_ENABLED true 启用或禁用函数级检测。设置为 false 以完全禁用。
OTEL_AWS_SERVICE_EVENTS_PACKAGES_INCLUDE 无（对于指标是必需的） 要检测的程序包前缀的逗号分隔列表。不需要通配符。例如：Java 使用 com.myapp，Python 使用 myapp，Node.js 使用 src/myapp。
OTEL_AWS_SERVICE_EVENTS_PACKAGES_EXCLUDE 无 要从检测中排除的子程序包的逗号分隔列表。排除始终优先于包含。例如，包含 com.myapp 和排除 com.myapp.models 可检测应用程序代码，但跳过数据模型类。

端点筛选

端点筛选控制哪些端点会生成端点错误指标和事件快照。这些设置不影响函数检测。

环境变量 默认值 说明
OTEL_AWS_SERVICE_EVENTS_ENDPOINT_INCLUDE_PATTERNS 所有端点 要包含的端点的逗号分隔 glob 模式。与 METHOD /route 匹配。
OTEL_AWS_SERVICE_EVENTS_ENDPOINT_EXCLUDE_PATTERNS 无 要排除的端点的逗号分隔 glob 模式。当一个端点同时匹配两者时，排除优先。

延迟阈值

使用下面的环境变量来配置事件快照触发器的延迟阈值。

环境变量 默认值 说明
OTEL_AWS_SERVICE_EVENTS_INCIDENT_SNAPSHOT_DURATION_THRESHOLD_MS 5000 全局延迟阈值（以毫秒为单位）。超过此持续时间的请求会触发事件快照。
OTEL_AWS_SERVICE_EVENTS_LATENCY_THRESHOLDS 无 覆盖全局默认值的每个端点延迟阈值。格式：METHOD /route:ms（例如 GET /health:200,POST /checkout:8000）。

速率限制

使用下面的环境变量来控制收集和报告服务事件数据的速率。

环境变量 默认值 说明
OTEL_AWS_SERVICE_EVENTS_INCIDENT_SNAPSHOT_MAX_PER_MINUTE 100 每分钟捕获的最大事件快照数量。
OTEL_AWS_SERVICE_EVENTS_INCIDENT_SNAPSHOT_MAX_SAME_ERROR 1 每个捕获窗口同一错误的最大快照数量。

配置部署事件

部署事件始终在应用程序启动时以及每 24 小时发出一次。提供部署元数据可丰富这些事件，以便您可以将事件和性能变化与特定代码部署相关联。

请对应用程序容器或进程设置下面的环境变量，以提供部署元数据：

环境变量 说明
OTEL_AWS_SERVICE_EVENTS_GIT_COMMIT_SHA 所部署代码的 Git 提交 SHA。
OTEL_AWS_SERVICE_EVENTS_GIT_REPO_URL Git 存储库的 URL。
OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_ID 部署的唯一标识符（例如 CI/CD 管线运行 ID）。
OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_TIMESTAMP 部署的 ISO 8601 时间戳。
OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_URL 部署构建或管线运行的 URL。

通过 GitHub Actions 配置部署事件

在 GitHub Actions 工作流中，请使用内置环境变量来填充部署元数据。请将以下内容添加到部署步骤或容器环境中：

env:
  OTEL_AWS_SERVICE_EVENTS_GIT_COMMIT_SHA: ${{ github.sha }}
  OTEL_AWS_SERVICE_EVENTS_GIT_REPO_URL: ${{ github.server_url }}/${{ github.repository }}
  OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_ID: ${{ github.run_id }}
  OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%SZ)
  OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

如果部署容器映像，请将这些值作为环境变量传递到任务定义或容器组（pod）规范中。您可以在构建时将它们嵌入到映像中，也可以在部署时通过部署配置注入它们。

通过 GitLab CI/CD 配置部署事件

在 GitLab CI/CD 管线中，请使用预定义的 CI/CD 变量来填充部署元数据。请将以下内容添加到部署作业中：

deploy:
  variables:
    OTEL_AWS_SERVICE_EVENTS_GIT_COMMIT_SHA: $CI_COMMIT_SHA
    OTEL_AWS_SERVICE_EVENTS_GIT_REPO_URL: $CI_PROJECT_URL
    OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_ID: $CI_PIPELINE_ID
    OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%SZ)
    OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_URL: $CI_PIPELINE_URL

在部署时通过容器编排平台将这些变量传递到应用程序容器（例如，作为 Amazon ECS 任务定义或 Kubernetes 部署清单中的环境变量）。