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

# 日誌警示
<a name="alarm-log"></a>

日誌警示會監控使用排程查詢依排程執行的 CloudWatch Logs Insights [查詢](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/ScheduledQueries.html)結果。警示會將彙總表達式套用至查詢結果以產生數值，當該彙總值超過設定的閾值時，警示會轉換為`ALARM`狀態並執行設定的動作。

與需要指標篩選條件做為中繼步驟的指標警示不同，日誌警示會使用您用於臨機操作分析的相同 Logs Insights 查詢語言，直接在日誌資料上進行評估。

## 日誌警示的運作方式
<a name="log-alarm-how-it-works"></a>

下列步驟說明日誌警示的運作方式：

1. 您可以使用查詢、彙總表達式、排程和閾值來建立日誌警示。

1. CloudWatch 會自動建立 AWS 受管排程查詢，以指定排程執行您的查詢。

1. 每個查詢執行都會產生彙總結果 （單一值或多個參與者值）。

1. CloudWatch 會使用最近查詢執行的 M-out-of-N 評估，針對您的閾值評估彙總結果。

1. 如果超過閾值，警示會轉換為 `ALARM` 狀態並執行您設定的動作 （例如 Amazon SNS 通知）。

**注意**  
日誌警示會評估最後 N 個查詢執行。當這些 N 執行的 M 超過閾值`ALARM`時，警示會轉換為 。

若要建立日誌警示，請參閱 [建立日誌警示](Alarm-On-Logs.md#Create_Log_Alarm)。

## 受管排程查詢生命週期
<a name="log-alarm-managed-query"></a>

當您建立日誌警示時，CloudWatch 會自動建立 AWS 受管排程查詢，以指定排程執行您的查詢。您不需要另外建立排程查詢。

 AWS 受管排程查詢具有下列特性：
+ 它會顯示在 CloudWatch Logs 主控台的排程查詢下。
+ 您無法直接修改它。若要變更查詢或其組態，請更新日誌警示。
+ 當您刪除警示時，CloudWatch 會刪除 AWS 受管排程查詢。

## 日誌警示組態
<a name="log-alarm-configuration"></a>

使用下列參數設定日誌警示：
+ **QueryString** 是要執行的 CloudWatch Logs Insights 查詢。
+ **LogGroupIdentifiers**是要查詢的日誌群組。指定日誌群組名稱或日誌群組 ARNs。
+ **ScheduledQueryRoleARN** 是 IAM 角色的 ARN，可讓 CloudWatch Logs 代表您執行排定的查詢。
+ **AggregationExpression** 定義如何將查詢結果彙總為數值以進行閾值評估。
+ **ScheduleExpression** 定義查詢執行的頻率 （例如 `rate(5 minutes)`)。
+ **StartTimeOffset** 會為每個查詢執行定義以秒為單位的回顧時段。
+ **EndTimeOffset** 將查詢時間範圍的結束定義為與目前時間的位移，以秒為單位。
+ **ComparisonOperator** 是彙總結果與閾值的比較方式。有效值：`GreaterThanThreshold`、`GreaterThanOrEqualToThreshold`、`LessThanThreshold`、`LessThanOrEqualToThreshold`。
+ **閾值**是要比較的數值。
+ **QueryResultsToEvaluate** 是要評估的最近查詢執行數目 (N，以 M-out-of-N 表示）。
+ **QueryResultsToAlarm** 是觸發所需的違規結果數量 `ALARM`(M M-out-of-N)。
+ **TreatMissingData** 定義如何在評估期間處理遺失的查詢結果。

如需參數和建立指示的完整清單，請參閱 [建立日誌警示](Alarm-On-Logs.md#Create_Log_Alarm)。

## 日誌查詢
<a name="log-alarm-query"></a>

日誌警示查詢是 CloudWatch Logs Insights 查詢，可選取和篩選要評估的日誌資料。查詢會在 中指定的日誌群組上執行，`LogGroupIdentifiers`超過 `StartTimeOffset`和 定義的時間範圍`EndTimeOffset`。

查詢使用 [CloudWatch Logs Insights 查詢語法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)。如需撰寫有效查詢日誌警示的指導方針，請參閱 [最佳實務和疑難排解](#log-alarm-best-practices)。

## 彙總表達式
<a name="log-alarm-aggregation"></a>

彙總表達式定義 CloudWatch 如何將查詢結果摘要為數值以進行閾值評估。表達式使用與 CloudWatch Logs Insights 中的 `stats`命令相同的語法。

彙總表達式的語法如下：

```
statistic_func_expression [by field1, field2, ...] [| sort asc|desc]
```

您只能指定單一彙總表達式。下表列出支援的彙總函數。


**支援的彙總函數**  

| 函式 | 說明 | 範例 | 
| --- | --- | --- | 
| count(\*) | 所有相符日誌行的計數。 | count(\*) | 
| avg(field) | 指定欄位的平均值。 | avg(duration) | 
| sum(field) | 指定欄位的總和。 | sum(bytesSent) | 
| min(field) | 指定欄位的最小值。 | min(latency) | 
| max(field) | 指定欄位的最大值。 | max(latency) | 

彙總表達式`by`子句中不支援 `bin()`函數。不過，您可以在查詢字串本身`bin()`中使用 。

## 多參與者警示
<a name="log-alarm-multi-contributor"></a>

當您在彙總表達式中包含`by`子句時，警示會獨立評估欄位值 （稱為*參與者*) 的每個唯一組合。如果任何參與者違反閾值，警示會轉換為 `ALARM` 狀態。

例如，下列表達式群組錯誤會依服務名稱計數：

```
count(*) by serviceName
```

的每個唯一值`serviceName`都會根據閾值獨立評估。如果任何服務超過 N 個查詢執行中 M 的閾值，警示會進入 `ALARM` 狀態。

下列限制適用於多提供者警示：
+ `by` 子句中最多 5 個欄位。
+ 每個查詢執行最多傳回 500 個參與者結果。
+ 最多 100 個參與者同時在 `ALARM` 狀態中追蹤。

根據預設，參與者會依字母順序排序，而且每個查詢執行只會傳回前 500 個。若要改為依參與者的彙總值排序參與者，請在彙總表達式`| sort desc`中指定 `| sort asc`或 （例如 `avg(latency) by serviceName | sort desc`)。以值為基礎的排序可確保在總數超過 500 時，先評估最重要的貢獻者。

對於多參與者警示，Amazon SNS 和 Lambda 動作會在參與者層級執行 （每個違規參與者一次）。Systems Manager OpsItem 動作會在警示層級執行。

**注意**  
日誌警示不支援 Systems Manager Incident Manager 和調查動作。

如果參與者從查詢結果中消失 （例如，暫時性資源已終止），則無論缺少資料處理設定，該參與者都會轉換為 `OK` 狀態。

## 遺失資料處理
<a name="log-alarm-missing-data"></a>

當排程查詢執行未產生可針對閾值評估的值時，就會發生遺失資料。這發生的情況如下：

**不存在日誌** — 日誌群組在查詢時間範圍中不包含日誌事件。

**查詢不會傳回任何適用的結果** — 日誌存在，但彙總表達式無法產生值。發生下列情況時會發生這種情況：
+ 根據查詢篩選條件，不存在相符的查詢結果。
+ 彙總表達式中參考的欄位不存在於查詢結果中。例如， `count(error-codes)` `error-codes`不存在於傳回的日誌事件中。

請注意，在空的結果集`count(*)`上傳回 0，這是有效的資料點，不會視為遺失。

您可以使用 `TreatMissingData` 參數來設定警示如何處理遺失的資料。下表說明可用的選項。


**缺少資料處理選項**  

| Value | Behavior (行為) | 
| --- | --- | 
| missing | 將資料點視為遺失。這是預設值。 | 
| notBreaching | 將遺失的資料點視為未超過閾值。 | 
| breaching | 將遺失的資料點視為違反閾值。 | 
| ignore | 忽略遺失的資料點，並僅評估可用的資料。 | 

## 評估狀態
<a name="log-alarm-evaluation-states"></a>

除了標準 `OK`、 `ALARM`和 `INSUFFICIENT_DATA` 狀態之外，日誌警示還可以在 `EvaluationState`欄位中報告下列評估狀態。這些狀態提供警示為何處於其目前狀態的其他內容。


**日誌警示評估狀態**  

| State | 說明 | 
| --- | --- | 
| EVALUATION\_FAILURE | 暫時性 CloudWatch 服務問題無法進行評估。當服務因為服務錯誤在評估查詢結果時遇到問題，或某些 （但並非所有） 查詢結果失敗時，就會發生這種情況。警示會轉換為 INSUFFICIENT\_DATA。我們建議手動監控，直到問題解決為止。 | 
| EVALUATION\_ERROR | 用戶端組態錯誤導致無法進行評估。這可能是由於許可不足、查詢無效，或當所有查詢結果都失敗。警示會INSUFFICIENT\_DATA立即轉換為 。如需詳細資訊，請參閱 StateReason 欄位。 | 
| PARTIAL\_DATA | 查詢傳回最多 500 個參與者群組，但更相符。警示會評估可用的參與者，但結果可能不完整。 | 

## 警示更新
<a name="log-alarm-update"></a>

當您更新日誌警示的查詢、彙總表達式、排程或日誌群組時，警示會轉換為 ，`INSUFFICIENT_DATA`直到收集到足夠的新資料點為止。變更閾值或 M-out-of-N 值不會觸發此重設。

## 動作和通知
<a name="log-alarm-notifications"></a>

日誌警示支援下列動作：
+ Amazon SNS 通知
+ Lambda 函數叫用
+ Systems Manager OpsItem 建立

如需完整的動作支援矩陣，請參閱 [警示動作](alarm-actions.md)。

當日誌警示轉換狀態時，動作通知會包含下列資訊：
+ 標準警示組態變更資訊 （警示名稱、描述、組態詳細資訊）。
+ 狀態變更資訊 （新狀態、狀態原因、時間戳記）。
+ Amazon SNS 電子郵件通知也包含 CloudWatch Logs Insights 主控台的深層連結，其中顯示完整的查詢結果。

下列範例顯示單一值日誌警示的 Amazon SNS 電子郵件通知 （不含 `BY`子句）：

```
{
    "AlarmName": "HighErrorCount",
    "NewStateValue": "ALARM",
    "NewStateReason": "Threshold Crossed: 3 out of the last 5 query results [142.0 (10/06/26 12:15:00), 135.0 (10/06/26 12:10:00), 120.0 (10/06/26 12:05:00)] were greater than the threshold (100.0) (minimum 3 datapoints for OK -> ALARM transition).",
    "NewStateReasonData": {
        "version": "1.0",
        "queryDate": "2026-06-10T12:15:30.000+0000",
        "threshold": 100.0,
        "queryResultsToEvaluate": 5,
        "queryResultsToAlarm": 3,
        "results": [
            {
                "queryResultId": "scheduled-query-execution-id-3",
                "status": "COMPLETE",
                "timestamp": "2026-06-10T12:15:00.000+0000",
                "value": 142.0
            }
            // Additional results...
        ]
    },
    "StateChangeTime": "2026-06-10T12:15:30.000+0000",
    "OldStateValue": "OK"
    // Additional fields...
}
```

下列範例顯示多參與者日誌警示 （含 `BY`子句） 的 Amazon SNS 電子郵件通知。每個違規參與者都會產生個別的通知：

```
{
    "AlarmName": "EndpointLatency",
    "NewStateValue": "ALARM",
    "NewStateReason": "5 out of 10 contributors evaluated to ALARM",
    "StateChangeTime": "2026-06-10T12:20:15.000+0000",
    "OldStateValue": "OK",
    "AlarmContributorId": "a1b2c3d4e5f6g7h8",
    "AlarmContributorAttributes": {
        "endpoint": "/api/orders"
    }
    // Additional fields...
}
```

### 在通知中包含日誌行
<a name="log-alarm-log-lines"></a>

您可以將 `ActionLogLineCount` 參數設定為介於 1 到 50 之間的值，選擇性地在警示通知中包含原始查詢結果日誌行。這些是評估彙總運算式的基礎日誌事件，而不是彙總值。預設值為 0，表示不包含日誌行。

**注意**  
日誌行僅包含在 Amazon SNS 電子郵件通知中。Lambda 動作不會在其承載中包含日誌行。

**重要**  
在通知中包含日誌行可能會在 Amazon SNS 訊息中公開來自日誌的敏感資料。啟用此功能之前，請先檢閱您的日誌內容。

若要包含日誌行，日誌行角色必須具有 `logs:GetQueryResults`許可。通知中包含的日誌行數受限於請求的計數、可用的總結果，以及 Amazon SNS 承載大小限制。

## 最佳實務和疑難排解
<a name="log-alarm-best-practices"></a>

### 最佳實務
<a name="log-alarm-bp"></a>

**查詢最佳化**
+ 在 CloudWatch Logs Insights 中手動測試查詢，然後在日誌警示中使用它們來驗證效能和預期結果。
+ 在查詢的早期使用篩選命令，以減少處理的資料量。
+ 限制查詢時間範圍 (StartTimeOffset)，以避免大量日誌群組逾時。
+ 使用欄位索引來最佳化查詢效能。

**排程規劃**
+ 選擇排程頻率，允許在下次執行之前完成查詢。對於大量日誌群組，請使用較長的間隔 （例如 10 分鐘而非 5 分鐘）。
+ 設定 StartTimeOffset 時記錄擷取延遲的帳戶。EndTimeOffset 與目前時間之間的小間隙有助於避免評估不完整的資料。
+ 將日誌警示排程分散至您的帳戶，以避免達到排程查詢並行限制。跨您帳戶的並行查詢執行不能超過 100。建立具有重疊排程的多個日誌警示時，請考量此配額。

**閾值調校**
+ 從較高的 QueryResultsToEvaluate (N) 值開始，以減少暫時性峰值的警示雜訊。
+ 對於稀疏事件 （例如很少發生的錯誤），請將 TreatMissingData 設定為 `notBreaching`，以在日誌不相符時將警示保持在 OK 狀態。
+ 對於持續訊號 （例如流量日誌），請考慮將 TreatMissingData 設定為 `breaching`，以偵測預期的日誌資料何時停止到達。

**多提供者設計**
+ 針對代表您要獨立監控之不同資源或維度的 BY 子句選擇有意義的欄位。
+ 請注意，每次查詢執行只會傳回前 500 個參與者。如果您預期更多，請縮小查詢範圍或使用較少的 BY 子句欄位。
+ 在彙總表達式中使用 `| sort desc`或 `| sort asc` 尾碼，在達到 500 個參與者限制時，根據您的比較運算子排定最高或最低值的優先順序。

### 疑難排解
<a name="log-alarm-troubleshooting"></a>

**警示保持在 INSUFFICIENT\_DATA 中**


| 可能的原因 | Resolution | 
| --- | --- | 
| 排程查詢執行角色缺少許可 | 確認角色具有範圍為正確日誌群組的 logs:GetQueryResults、、 logs:StartQuery logs:StopQuery和 logs:DescribeLogGroups許可。 | 
| 日誌群組不存在或已刪除 | 確認警示組態中的日誌群組 ARNs 正確且可存取。 | 
| 最近建立或更新的警示 | 建立或組態更新之後，警示會保留在 INSUFFICIENT\_DATA 中，直到足夠的查詢執行完成，以滿足 M-out-of-N評估時段為止。 | 
| 排程查詢未執行 | 在 CloudWatch Logs 主控台中檢查 AWS 受管排程查詢，以確認其是否按排程執行。 | 
| 彙總欄位不存在於查詢結果中 | 彙總表達式中參考的欄位必須存在於查詢結果中。例如，如果您的彙總是 avg(latency)，請確定查詢會產生 latency 欄位。如果 欄位不存在，則會將結果視為遺失資料。 | 
| 日誌擷取延遲 | 排程查詢只能評估執行時已擷取的日誌事件。 `StartTimeOffset`和 會`EndTimeOffset`定義相對於執行時間 T — 【T − StartTimeOffset、T − EndTimeOffset】 的查詢時段，但不會考慮擷取延遲。如果您查詢的時段仍在擷取事件，查詢會在可用之前執行並略過它們。<br />使用 將視窗向後`EndTimeOffset`移動到足以完成整個範圍的擷取。<br />範例：假設日誌在事件發生後最多需要 2 分鐘才能變成可查詢。+  `StartTimeOffset=60, EndTimeOffset=0` — window 【T−60s， T】。視窗會在執行時間結束，因此最近的事件尚未擷取且遺失。 <br />+  `StartTimeOffset=180, EndTimeOffset=120` — window 【T−180s、T−120s】。視窗在過去 2 分鐘結束，此時所有事件都會被擷取且可評估。  | 

**警示顯示 EVALUATION\_ERROR**

這表示用戶端組態問題。如需詳細資訊，請參閱 StateReason 欄位。常見原因：
+ 無效或格式不正確的查詢語法。
+ 排程查詢執行角色的許可不足。
+ 所有查詢執行失敗 （例如，日誌群組許可已撤銷）。

**警示顯示 EVALUATION\_FAILURE**

這表示暫時性 CloudWatch 服務問題。當問題解決時，警示會自動復原。如果持續超過幾分鐘，請檢查 CloudWatch 服務運作狀態儀表板。

**警示顯示 PARTIAL\_DATA**

查詢傳回最多 500 個參與者群組，但更相符。警示會評估可用的參與者，但結果可能不完整。考慮縮小查詢範圍或減少 BY 子句欄位的數量。

**日誌行未出現在通知中**
+ 確認`ActionLogLineCount`設定為介於 1 到 50 之間的值。
+ 確認日誌列角色具有範圍為正確日誌群組的`logs:GetQueryResults`許可。
+ 日誌行僅包含在 Amazon SNS 電子郵件通知中。其他動作類型不包含日誌行。
+ 使用 的查詢`unmask()`無法在通知中包含日誌行 （在建立時拒絕）。

如需查詢最佳化、監控和授權的其他最佳實務，請參閱《*Amazon CloudWatch Logs 使用者指南*》中的[排程查詢最佳實務](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/scheduled-queries-best-practices.html)。