# 监控服务事件
利用服务事件可自动深度观察通过 CloudWatch Application Signals 监控的服务。它会捕获错误指标、函数级性能数据、事件快照（当请求超过延迟阈值或引发异常时）和部署事件，而无需额外的代码更改。
## 服务事件的工作原理
服务事件会从检测的服务中收集以下类型的信号：
+ **错误指标**：每项操作的每种异常类型的错误计数和比率，使您能够识别哪些异常最频繁且呈上升趋势。
+ **函数调用指标**：应用程序代码中各个函数的调用计数、持续时间和错误率。
+ **事件快照**：当请求超过延迟阈值或引发异常时触发的详细捕获，包括堆栈跟踪、调用树、调用者详细信息和操作上下文。
+ **部署事件**：应用程序启动时和每 24 小时发出的标记，可将代码部署与服务行为的变化相关联。应用程序会自动发出部署事件。提供部署元数据（git commit、部署 ID）可为这些事件提供更多上下文。
当为服务启用 CloudWatch Application Signals 时，服务事件会自动启用。错误指标和异常跟踪将立即生效。函数调用指标需要其他配置：在收集函数调用数据之前必须配置要检测的程序包（请参阅 [启用函数检测](#Application-Signals-ServiceEvents-Configure-Function)）。可以通过设置 `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**。
1. 为服务选择日志组 `/aws/service-events/{{service-name}}`。
1. 输入一个查询以筛选和分析服务事件数据。
## CloudWatch Application Signals MCP（模型上下文协议）服务器中的服务事件
服务事件数据可通过 CloudWatch Application Signals MCP（模型上下文协议）服务器访问，从而使人工智能编码助手和代理能够直接查询服务的运行时行为。
**故障排查**
+ 自动将代码中的错误与生产事件快照相关联，包括完整的堆栈跟踪和受影响的端点。
+ 使用事件上下文（异常类型、调用路径、跟踪 ID）提出有针对性的修复建议，而无需手动导航控制面板。
+ 检索部署事件，以确定最新版本是否引入了回归。
**性能改进**
+ 在调查延迟问题时查询函数级性能数据以识别瓶颈。
+ 比较不同部署的函数调用持续时间以查明性能回归情况。
有关设置和使用说明，请参阅 GitHub 网站上的 [Application Signals MCP 服务器](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。
## 配置服务事件
### 先决条件
要使用服务事件，请确保您拥有下列组件所需的最低版本：
1. **更新 ADOT SDK**：将适用于您的语言（Java、Python 或 Node.js）的 Amazon Distro for OpenTelemetry（ADOT）检测 SDK 更新到最新版本。
1. **更新 Amazon EKS 附加组件（若适用）**：如果使用 CloudWatch Observability Amazon EKS 附加组件来检测应用程序，请更新到该附加组件的最新版本。
1. **更新 CloudWatch 代理**：更新到 CloudWatch 代理的版本 `1.300069.0` 或更高版本。
如果使用 Amazon EKS，请参阅 [在 Amazon EKS 集群上启用应用程序](CloudWatch-Application-Signals-Enable-EKS.md)，了解附加组件设置说明。
### 默认启用的功能
如果使用 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 部署清单中的环境变量）。