本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 監控服務事件
<a name="CloudWatch-Application-Signals-ServiceEvents"></a>

Service Events 為使用 CloudWatch Application Signals 監控的服務提供自動化的深度可觀測性。它會擷取錯誤指標、函數層級效能資料、事件快照 （當請求超過延遲閾值或擲回例外狀況時） 和部署事件，而不需要額外的程式碼變更。

## 服務事件的運作方式
<a name="Application-Signals-ServiceEvents-HowItWorks"></a>

Service Events 會從您的檢測服務收集下列類型的訊號：
+ **錯誤指標** — Per-exception-type錯誤計數和每個操作的速率，可讓您識別哪些例外狀況最常發生和出現趨勢。
+ **函數呼叫指標** — 應用程式程式碼中個別函數的調用計數、持續時間和錯誤率。
+ **事件快照** — 請求超過延遲閾值或擲回例外狀況時觸發的詳細擷取，包括堆疊追蹤、呼叫樹狀目錄、呼叫者詳細資訊和操作內容。
+ **部署事件** — 在應用程式啟動時和每 24 小時發出的標記，這些標記會將程式碼部署與服務行為變更建立關聯。應用程式會自動發出部署事件。提供部署中繼資料 (git 遞交、部署 ID) 可讓這些事件具有額外的內容。

當您為服務啟用 CloudWatch Application Signals 時，會自動啟用服務事件。錯誤指標和例外狀況追蹤會立即作用中。函數呼叫指標需要額外的組態 - 您必須先將套件設定為檢測，才能收集函數呼叫資料 （請參閱 [啟用函數檢測](#Application-Signals-ServiceEvents-Configure-Function))。您可以透過設定 來停用服務事件`OTEL_AWS_SERVICE_EVENTS_ENABLED=false`。從 ADOT 開發套件到 CloudWatch 代理程式的資料流程。代理程式會將事件發佈至 CloudWatch Logs (`/aws/service-events/{{service-name}}` 日誌群組） 和 CloudWatch 指標。

支援的語言：Java、Python 和 Node.js。

**注意**  
服務事件會在 Lambda 環境中自動停用。

## 資料儲存
<a name="Application-Signals-ServiceEvents-DataStorage"></a>

Service Events 會將資料存放在 CloudWatch Logs 中。CloudWatch 會將服務事件資料發佈至字首為 的日誌群組`/aws/application-signals/{{service-name}}`，其中 {{service-name}} 是您`OTEL_SERVICE_NAME`環境變數的值。每個服務建立一個日誌群組。

您需要按標準 CloudWatch Logs 費率支付日誌擷取和儲存的費用。

## 在主控台中檢視錯誤
<a name="Application-Signals-ServiceEvents-Errors"></a>

在 CloudWatch 主控台中，導覽至 **Application Signals**，選擇您的服務，然後選擇**錯誤**索引標籤。此標籤顯示 服務的例外狀況指標。

索引標籤會顯示：
+ 例外計數圖表顯示隨時間變化的錯誤趨勢。使用此項目可偵測最近發生頻率變更的例外狀況類型。
+ 列出每個例外狀況類型的資料表、發生的操作、發生計數，以及與上一個期間相比的變更。

選取例外狀況以深入了解詳細資訊，包括堆疊追蹤、例外狀況訊息，以及關聯追蹤的連結。

錯誤會依操作、例外狀況類型和最高堆疊影格分組。只會顯示每個群組的最新代表。

**注意**  
若要檢視錯誤資料，您的帳戶中必須至少有一個`/aws/service-events/{{service-name}}`日誌群組。如果不存在日誌群組，錯誤索引標籤會顯示加入提示。

## 在日誌中檢視服務事件
<a name="Application-Signals-ServiceEvents-Logs"></a>

Service Events 資料存放在 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 （模型內容通訊協定） 伺服器中的服務事件
<a name="Application-Signals-ServiceEvents-MCP"></a>

服務事件資料可透過 CloudWatch Application Signals MCP （模型內容通訊協定） 伺服器存取，讓 AI 編碼助理和客服人員可以直接查詢服務的執行時間行為。

**疑難排解**
+ 自動將程式碼中的錯誤與生產事件快照建立關聯，包括完整堆疊追蹤和受影響的端點。
+ 使用事件內容 （例外類型、呼叫路徑、追蹤 IDs) 建議目標修正，而不需要您手動導覽儀表板。
+ 擷取部署事件，以判斷最近的版本是否引入迴歸。

**效能改善**
+ 查詢函數層級效能資料，以在調查延遲問題時識別瓶頸。
+ 比較跨部署的函數呼叫持續時間，以精確找出效能迴歸。

如需設定和使用說明，請參閱 GitHub 網站上的 [Application Signals MCP 伺服器](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

## 設定服務事件
<a name="Application-Signals-ServiceEvents-Configure"></a>

### 先決條件
<a name="Application-Signals-ServiceEvents-Configure-Prerequisites"></a>

若要使用服務事件，請確定您擁有下列元件所需的最低版本：

1. **更新 ADOT SDK** — 將 AWS Distro for OpenTelemetry (ADOT) 檢測 SDK 更新為您的語言 (Java、Python 或 Node.js) 的最新版本。

1. **更新 Amazon EKS 附加元件 （如適用）** — 如果您使用 CloudWatch 可觀測性 Amazon EKS 附加元件來檢測您的應用程式，請更新至最新版本的附加元件。

1. **更新 CloudWatch 代理程式** — 更新至 CloudWatch 代理程式版本 `1.300069.0`或更新版本。

如果您使用 Amazon EKS，請參閱 [在 Amazon EKS 叢集上啟用 Application Signals](CloudWatch-Application-Signals-Enable-EKS.md) 以取得附加元件設定指示。

### 預設啟用的功能
<a name="Application-Signals-ServiceEvents-Configure-Defaults"></a>

如果您使用 CloudWatch Application Signals，**則預設會啟用**下列服務事件訊號，而不需要額外的組態：
+ 事件快照 （在例外狀況和延遲閾值違規時觸發）
+ 錯誤指標 per-exception-type錯誤計數）
+ 部署事件 （一律發出；當您提供部署中繼資料時富集）
+ 函數檢測 （預設為啟用，但除非您將套件設定為檢測，否則不會產生指標）

下列功能為**選擇加入**，需要設定環境變數才能產生資料：
+ 函數層級指標 （需要設定 `OTEL_AWS_SERVICE_EVENTS_PACKAGES_INCLUDE`)
+ 自訂端點篩選
+ 每個端點延遲閾值

### 一般設定
<a name="Application-Signals-ServiceEvents-Configure-General"></a>


| 環境變數 | 預設 | 說明 | 
| --- | --- | --- | 
| OTEL\_AWS\_SERVICE\_EVENTS\_ENABLED | 遵循 CloudWatch Application Signals | 切換服務事件。服務事件會在 CloudWatch Application Signals 啟用時自動啟用。設定為 false以明確停用。 | 
| OTEL\_AWS\_SERVICE\_EVENTS\_SAMPLING\_MODE | always | 控制函數呼叫資料取樣策略。值： always （記錄所有函數呼叫）、 auto（讓 SDK 根據負載決定）、 never（停用函數呼叫記錄）。僅適用於設定函數檢測套件時。 | 

### 啟用函數檢測
<a name="Application-Signals-ServiceEvents-Configure-Function"></a>

函數檢測預設為啟用，但在您設定要檢測的套件之前，不會產生指標。提供套件允許清單以開始收集每個函數遙測：


| 環境變數 | 預設 | 說明 | 
| --- | --- | --- | 
| OTEL\_AWS\_SERVICE\_EVENTS\_FUNCTION\_INSTRUMENT\_ENABLED | true | 啟用或停用函數層級檢測。設定為 false以完全停用。 | 
| OTEL\_AWS\_SERVICE\_EVENTS\_PACKAGES\_INCLUDE | 無 （指標需要） | 要檢測的逗號分隔套件字首清單。不需要萬用字元。例如：Java 使用 com.myapp，Python 使用 myapp，Nodesrc/myapp.js 使用 。 | 
| OTEL\_AWS\_SERVICE\_EVENTS\_PACKAGES\_EXCLUDE | 無 | 要從檢測中排除的逗號分隔子套件清單。排除一律優先於包含。例如，包含com.myapp和排除 com.myapp.models以檢測您的應用程式程式碼，但略過資料模型類別。 | 

### 端點篩選
<a name="Application-Signals-ServiceEvents-Configure-Endpoint"></a>

端點篩選可控制哪些端點產生端點錯誤指標和事件快照。這些設定不會影響函數檢測。


| 環境變數 | 預設 | 說明 | 
| --- | --- | --- | 
| OTEL\_AWS\_SERVICE\_EVENTS\_ENDPOINT\_INCLUDE\_PATTERNS | 所有端點 | 要包含之端點的逗號分隔 glob 模式。符合 METHOD /route。 | 
| OTEL\_AWS\_SERVICE\_EVENTS\_ENDPOINT\_EXCLUDE\_PATTERNS | 無 | 要排除之端點的逗號分隔 glob 模式。當端點同時符合兩者時，排除優先。 | 

### 延遲閾值
<a name="Application-Signals-ServiceEvents-Configure-Latency"></a>

使用下列環境變數來設定事件快照觸發的延遲閾值。


| 環境變數 | 預設 | 說明 | 
| --- | --- | --- | 
| 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)。 | 

### 速率限制
<a name="Application-Signals-ServiceEvents-Configure-RateLimit"></a>

使用下列環境變數來控制收集和報告服務事件資料的速率。


| 環境變數 | 預設 | 說明 | 
| --- | --- | --- | 
| OTEL\_AWS\_SERVICE\_EVENTS\_INCIDENT\_SNAPSHOT\_MAX\_PER\_MINUTE | 100 | 每分鐘擷取的事件快照數目上限。 | 
| OTEL\_AWS\_SERVICE\_EVENTS\_INCIDENT\_SNAPSHOT\_MAX\_SAME\_ERROR | 1 | 每個擷取時段相同錯誤的快照數目上限。 | 

## 設定部署事件
<a name="Application-Signals-ServiceEvents-DeploymentEvents"></a>

部署事件一律會在應用程式啟動和每 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 動作設定部署事件
<a name="Application-Signals-ServiceEvents-DeploymentEvents-GitHub"></a>

在您的 GitHub 動作工作流程中，使用內建環境變數來填入部署中繼資料。將下列項目新增至您的部署步驟或容器環境：

```
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 設定部署事件
<a name="Application-Signals-ServiceEvents-DeploymentEvents-GitLab"></a>

在您的 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 部署資訊清單中的環境變數）。