View a markdown version of this page

監控服務事件 - Amazon CloudWatch
服務事件的運作方式資料儲存在主控台中檢視錯誤在日誌中檢視服務事件CloudWatch Application Signals MCP （模型內容通訊協定） 伺服器中的服務事件設定服務事件設定部署事件

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

監控服務事件

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

服務事件的運作方式

Service Events 會從您的檢測服務收集下列類型的訊號：

  • 錯誤指標 — Per-exception-type錯誤計數和每個操作的速率，可讓您識別哪些例外狀況最常發生和出現趨勢。

  • 函數呼叫指標 — 應用程式程式碼中個別函數的調用計數、持續時間和錯誤率。

  • 事件快照 — 請求超過延遲閾值或擲回例外狀況時觸發的詳細擷取，包括堆疊追蹤、呼叫樹狀目錄、呼叫者詳細資訊和操作內容。

  • 部署事件 — 在應用程式啟動時和每 24 小時發出的標記，這些標記會將程式碼部署與服務行為變更建立關聯。應用程式會自動發出部署事件。提供部署中繼資料 (git 遞交、部署 ID) 可讓這些事件具有額外的內容。

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

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

注意

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

資料儲存

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

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

在主控台中檢視錯誤

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

索引標籤會顯示：

  • 例外計數圖表顯示隨時間變化的錯誤趨勢。使用此項目可偵測最近發生頻率變更的例外狀況類型。

  • 列出每個例外狀況類型的資料表、發生的操作、發生計數，以及與上一個期間相比的變更。

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

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

注意

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

在日誌中檢視服務事件

Service Events 資料存放在 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 （模型內容通訊協定） 伺服器存取，讓 AI 編碼助理和客服人員可以直接查詢服務的執行時間行為。

疑難排解

  • 自動將程式碼中的錯誤與生產事件快照建立關聯，包括完整堆疊追蹤和受影響的端點。

  • 使用事件內容 （例外類型、呼叫路徑、追蹤 IDs) 建議目標修正，而不需要您手動導覽儀表板。

  • 擷取部署事件，以判斷最近的版本是否引入迴歸。

效能改善

  • 查詢函數層級效能資料，以在調查延遲問題時識別瓶頸。

  • 比較跨部署的函數呼叫持續時間，以精確找出效能迴歸。

如需設定和使用說明，請參閱 GitHub 網站上的 Application Signals MCP 伺服器。

設定服務事件

先決條件

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

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

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

  3. 更新 CloudWatch 代理程式 — 更新至 CloudWatch 代理程式版本 1.300069.0或更新版本。

如果您使用 Amazon EKS，請參閱 在 Amazon EKS 叢集上啟用 Application Signals 以取得附加元件設定指示。

預設啟用的功能

如果您使用 CloudWatch Application Signals，則預設會啟用下列服務事件訊號，而不需要額外的組態：

  • 事件快照 （在例外狀況和延遲閾值違規時觸發）

  • 錯誤指標 per-exception-type錯誤計數）

  • 部署事件 （一律發出；當您提供部署中繼資料時富集）

  • 函數檢測 （預設為啟用，但除非您將套件設定為檢測，否則不會產生指標）

下列功能為選擇加入，需要設定環境變數才能產生資料：

  • 函數層級指標 （需要設定 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，Nodesrc/myapp.js 使用 。
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 動作設定部署事件

在您的 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 設定部署事件

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