# ログアラーム
ログアラームは、[スケジュールされたクエリ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/ScheduledQueries.html)を使用してスケジュールに従って実行される CloudWatch Logs Insights クエリの結果をモニタリングします。アラームは集計式をクエリ結果に適用して数値を生成し、その集計値が設定されたしきい値を超えると、アラームは `ALARM` 状態に移行し、設定されたアクションを実行します。
ログアラームは、中間ステップとしてメトリクスフィルターを必要とするメトリクスアラームとは異なり、アドホック分析に使用するのと同じ Logs Insights クエリ言語を使用してログデータを直接評価します。
## ログアラームの仕組み
次の手順はログアラームの仕組みについて説明したものです。
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)」を参照してください。
## マネージドのスケジュールされたクエリのライフサイクル
ログアラームを作成すると、CloudWatch は、指定されたスケジュールでクエリを実行する AWS マネージドのスケジュールされたクエリを自動的に作成します。スケジュールされたクエリを個別に作成する必要はありません。
AWS マネージドのスケジュールされたクエリには次の特性があります。
+ これは、CloudWatch Logs コンソールの [スケジュールされたクエリ] に表示されます。
+ 直接変更することはできません。クエリまたはその設定を変更するには、ログアラームを更新します。
+ アラームを削除すると、CloudWatch は AWS マネージドのスケジュールされたクエリを削除します。
## ログアラームの設定
ログアラームは、次のパラメータで設定されます。
+ **QueryString** は、実行する CloudWatch Logs Insights クエリです。
+ **LogGroupIdentifiers** は、クエリするロググループです。ロググループ名またはロググループ ARN を指定します。
+ **ScheduledQueryRoleARN** は、スケジュールされたクエリを CloudWatch Logs がユーザーに代わって実行できるようにする IAM ロールの ARN です。
+ **AggregationExpression** は、クエリ結果をしきい値評価のために数値に集約する方法を定義します。
+ **ScheduleExpression** は、クエリの実行頻度を定義します (例: `rate(5 minutes)`)。
+ **StartTimeOffset** は、クエリ実行ごとにルックバックウィンドウを秒単位で定義します。
+ **EndTimeOffset** は、クエリ時間範囲の終了を、現在の時刻からの秒単位のオフセットとして定義します。
+ **ComparisonOperator** は、集計結果をしきい値と比較する方法です。有効な値は、`GreaterThanThreshold`、`GreaterThanOrEqualToThreshold`、`LessThanThreshold`、`LessThanOrEqualToThreshold` です。
+ **Threshold** は、比較対象の数値です。
+ **QueryResultsToEvaluate** は、評価する最近のクエリ実行の数です (M-out-of-N の N)。
+ **QueryResultsToAlarm** は、`ALARM` をトリガーするために必要な違反結果の数です (M-out-of-N の M)。
+ **TreatMissingData** は、欠落しているクエリ結果が評価中にどのように処理されるかを定義します。
パラメータの完全なリストと作成手順については、[ログアラームの作成](Alarm-On-Logs.md#Create_Log_Alarm) を参照してください。
## ログクエリ
ログアラームクエリは、評価するログデータを選択してフィルタリングする CloudWatch Logs Insights クエリです。このクエリは、`StartTimeOffset` および `EndTimeOffset` で定義された時間範囲にわたって、`LogGroupIdentifiers` で指定されたロググループで実行されます。
このクエリは [CloudWatch Logs Insights のクエリ構文](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)を使用します。ログアラームの効率的なクエリの記述に関するガイドラインについては、「[ベストプラクティスとトラブルシューティング](#log-alarm-best-practices)」を参照してください。
## 集計式
集計式は、CloudWatch がクエリ結果をしきい値評価の数値にまとめる方法を定義します。この式は、CloudWatch Logs Insights の `stats` コマンドと同じ構文を使用します。
集計式の構文は次のとおりです。
```
statistic_func_expression [by field1, field2, ...] [| sort asc|desc]
```
指定できる集計式は 1 つだけです。次の表に、サポートされている集計関数を示します。
**サポートされている集計関数**
| 関数 | 説明 | 例 |
| --- | --- | --- |
| count(\*) | 一致するすべてのログ行の数。 | count(\*) |
| avg(field) | 指定したフィールドの平均値。 | avg(duration) |
| sum(field) | 指定したフィールドの合計。 | sum(bytesSent) |
| min(field) | 指定したフィールドの最小値。 | min(latency) |
| max(field) | 指定したフィールドの最大値。 | max(latency) |
`bin()` 関数は、集計式の `by` 句ではサポートされていません。ただし、クエリ文字列自体で `bin()` を使用できます。
## マルチコントリビューターアラーム
集計式に `by` 句を含めると、アラームはフィールド値の一意の各組み合わせ (「コントリビューター」と呼ばれる) を個別に評価します。いずれかのコントリビューターがしきい値を超えた場合、アラームは `ALARM` 状態に移行します。
たとえば、次の式はサービス名でエラー数をグループ化します。
```
count(*) by serviceName
```
`serviceName` の一意の各値は、しきい値に対して個別に評価されます。いずれかのサービスが N 回のクエリ実行のうちしきい値を M 回超えると、アラームは `ALARM` 状態になります。
マルチコントリビューターアラームには次の制限が適用されます。
+ `by` 句の最大フィールド数は 5 つです。
+ クエリの実行ごとに返されるコントリビューターの結果の最大数は 500 です。
+ 最大 100 個のコントリビューターが同時に `ALARM` 状態で追跡されます。
デフォルトでは、コントリビューターはアルファベット順にソートされ、クエリの実行ごとに最初の 500 個のみが返されます。あるいは、コントリビューターを集計値でソートする場合は、集計式で `| sort asc` または `| sort desc` を指定します (例: `avg(latency) by serviceName | sort desc`)。値ベースのソートでは、合計数が 500 を超えると、最も重要なコントリビューターが最初に評価されます。
マルチコントリビューターアラームの場合、Amazon SNS と Lambda アクションはコントリビューターレベルで実行されます (違反しているコントリビューターごとに 1 回)。Systems Manager の OpsItem アクションはアラームレベルで実行されます。
**注記**
Systems Manager Incident Manager と調査アクションは、ログアラームではサポートされていません。
コントリビューターがクエリ結果から消えた場合 (エフェメラルリソースが終了した場合など)、そのコントリビューターは、欠落しているデータ処理設定に関係なく `OK` 状態に移行します。
## 欠損データ処理
欠落データは、スケジュールされたクエリ実行がしきい値に対して評価できる値を生成しない場合に発生します。次の場合に発生:
**ログが存在しない** — ロググループにクエリ時間範囲内のログイベントが含まれていません。
**クエリが該当する結果を返さない** — ログは存在しますが、集計式は値を生成できません。これは次のような場合に起こります。
+ クエリフィルターの条件に合致するクエリ結果が存在しなかった場合。
+ クエリ結果には集計式で参照されるフィールドが存在しなかった場合。たとえば、返されたログイベントに `error-codes` が存在しない `count(error-codes)` など。
空の結果セットの `count(*)` では、有効なデータポイントで欠落として扱われない 0 が返されることに注意してください。
アラームが `TreatMissingData` パラメータを使用して欠落データを処理する方法を設定できます。次の表では利用可能なオプションを説明しています。
**欠落データ処理オプション**
| 値 | 動作 |
| --- | --- |
| missing | データポイントを欠落として扱います。これがデフォルトです。 |
| notBreaching | 欠損データをしきい値に違反していないものとして扱います。 |
| breaching | 欠損データをしきい値に違反しているものとして扱います。 |
| ignore | 欠落しているデータポイントを無視し、使用可能なデータのみを評価します。 |
## 評価ステータス
ログアラームは、標準の `OK`、`ALARM`、`INSUFFICIENT_DATA` 状態に加えて、`EvaluationState` フィールドで次の評価状態をレポートできます。これらの状態は、アラームが現在の状態にある理由に関する追加のコンテキストを示します。
**ログアラーム評価状態**
| 状態 | 説明 |
| --- | --- |
| EVALUATION\_FAILURE | 一時的な CloudWatch サービス問題により評価が妨げられました。これは、サービスエラーによりクエリ結果の評価に問題が生じた場合、または一部の（すべてではない）クエリ結果の取得に失敗した場合に発生する可能性があります。アラームは INSUFFICIENT\_DATA に移行します。問題が解決するまでは手動でモニタリングを行うことが推奨されます。 |
| EVALUATION\_ERROR | クライアント設定エラーにより評価が妨げられました。これは、アクセス許可の不足、無効なクエリ、またはすべてのクエリ結果が失敗したために発生する可能性があります。アラームはすぐに INSUFFICIENT\_DATA に移行します。詳細については StateReason フィールドを参照してください。 |
| PARTIAL\_DATA | クエリは最大 500 個のコントリビューターグループを返しましたが、それ以上の数のグループが一致しています。アラームは使用可能なコントリビューターを評価しますが、結果は不完全である可能性があります。 |
## アラームの更新
ログアラームのクエリ、集計式、スケジュール、またはロググループを更新すると、十分な新しいデータポイントが収集されるまで、アラームは `INSUFFICIENT_DATA` に移行します。しきい値または M-out-of-N 値を変更しても、このリセットはトリガーされません。
## アクションおよび通知
ログアラームでは以下のアクションがサポートされています。
+ Amazon SNSの通知
+ Lambda 関数の呼び出し
+ Systems Manager OpsItem の作成
アクションサポートマトリックスの詳細については、「[アラームアクション](alarm-actions.md)」を参照してください。
ログアラームの状態が移行すると、アクション通知には次の情報が含まれます。
+ 標準アラーム設定変更情報 (アラーム名、説明、設定の詳細)。
+ 状態変更情報 (新しい状態、状態の理由、タイムスタンプ)。
+ Amazon SNS 電子メール通知には CloudWatch Logs Insights コンソールへのディープリンクも含まれており、完全なクエリ結果を確認できます。
次の例は、単一値ログアラーム (`BY` 句なし) の Amazon SNS 電子メール通知を示しています。
```
{
"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...
}
```
### 通知にログ行を含める
オプションで、`ActionLogLineCount` パラメータを 1 ～ 50 の値に設定することで、未加工のクエリ結果のログ行をアラーム通知に含めることができます。これらは集計値ではなく、集計式の評価基盤となるログイベントです。デフォルト値は 0 で、ログ行は含まれません。
**注記**
ログ行は Amazon SNS 電子メール通知にのみ含まれます。Lambda アクションによりペイロードにログ行が含まれることはありません。
**重要**
通知にログ行を含めると、Amazon SNS メッセージのログから機密データが公開される可能性があります。この機能を有効にする際には事前にログの内容を確認してください。
ログ行を含めるには、ログ行ロールに `logs:GetQueryResults` アクセス許可が必要です。通知に含まれるログ行の数は、リクエストされた数、使用可能な合計結果、および Amazon SNS ペイロードサイズ制限によって制限されます。
## ベストプラクティスとトラブルシューティング
### ベストプラクティス
**クエリの最適化**
+ ログアラームで使用する前に、CloudWatch Logs Insights でクエリを手動でテストして、パフォーマンスと期待される結果を確認してください。
+ クエリの早い段階でフィルターコマンドを使用して、処理されるデータ量を減らします。
+ クエリの時間範囲 (StartTimeOffset) を制限して、大量のロググループのタイムアウトを回避します。
+ フィールドインデックスを使用してクエリのパフォーマンスを最適化します。
**スケジュール計画**
+ 次の実行の前にクエリを完了できるようにスケジュール頻度を選択します。ロググループが大量にある場合は、間隔を長め (5 分ではなく 10 分など) にします。
+ StartTimeOffset を設定するときのログ取り込みの遅延を考慮します。EndTimeOffset と現在の時刻の間に小さなギャップがあると、不完全なデータの評価を回避できます。
+ スケジュールされたクエリの同時実行数の制限に達しないように、ログアラームのスケジュールをアカウントに分散させます。アカウント全体での同時クエリ実行数の上限は 100 です。スケジュールが重複しているログアラームを複数作成するときは、このクォータを考慮してください。
**しきい値の調整**
+ QueryResultsToEvaluate (N) の値を大きくして、一時的なスパイクによるアラームノイズを減らします。
+ スパースイベント (まれに発生するエラーなど) の場合、一致するログがない場合にアラームを OK 状態に保つために、TreatMissingData を `notBreaching` に設定します。
+ 連続シグナル (トラフィックログなど) の場合は、予想されるログデータがいつ到着しなくなるかを検出するために、TreatMissingData を `breaching` に設定することを検討してください。
**マルチコントリビューター設計**
+ 別途モニタリングする個別のリソースまたはディメンションを表す BY 句のために、有意義なフィールドを選択します。
+ クエリの実行ごとに返されるコントリビューターは、最初の 500 個のみであることに注意してください。500 個以上にしたい場合は、クエリを絞り込むか、使用する BY 句フィールドの数を減らします。
+ 集計式の `| sort desc` または `| sort asc` サフィックスを使用して、コントリビューターの上限である 500 に達したときに、比較演算子に基づいて最大値または最小値を優先します。
### トラブルシューティング
**アラームが INSUFFICIENT\_DATA にとどまる**
| 考えられる原因 | 解決策 |
| --- | --- |
| スケジュールされたクエリ実行ロールにアクセス許可がない | 正しいロググループにスコープされたアクセス許可 logs:StartQuery、logs:StopQuery、logs:GetQueryResults、logs:DescribeLogGroups がロールにあることを確認してください。 |
| ロググループが存在しないか、削除された | アラーム設定のロググループ ARN が正しく、アクセス可能であることを確認してください。 |
| アラームが最近作成または更新された | 作成または設定の更新後、M-out-of-N 評価ウィンドウを満たすのに十分なクエリ実行が完了するまで、アラームは INSUFFICIENT\_DATA のままになります。 |
| スケジュールされたクエリが実行されていない | CloudWatch Logs コンソールで AWS マネージドのスケジュールされたクエリを確認して、スケジュールどおりに実行されていることを確認してください。 |
| クエリ結果に集計フィールドが存在しない | クエリ結果には、集計式で参照されるフィールドが存在していなければなりません。たとえば、集計が avg(latency) の場合、クエリで latency フィールドが生成されていることを確認してください。このフィールドが存在しない場合、その結果は欠落データとして扱われます。 |
| ログ取り込みの遅延 | スケジュールされたクエリは、実行時に取り込まれたログイベントのみを評価できます。`StartTimeOffset` と `EndTimeOffset` は、実行時間 T を基準にしたクエリウィンドウ — [T − StartTimeOffset、T − EndTimeOffset] — を定義しますが、取り込みの遅延は考慮されません。クエリするウィンドウのイベントがまだ取り込まれている場合、クエリは使用可能になる前に実行され、スキップされます。
`EndTimeOffset` を使用して、範囲全体の取り込みが完了するのに十分なだけウィンドウを過去にずらします。
例: イベントの発生後にログがクエリ可能になるまでに最大 2 分かかるとします。+ `StartTimeOffset=60, EndTimeOffset=0` — ウィンドウ [T−60s、T]。ウィンドウは実行時に終了するため、最近のイベントはまだ取り込まれておらず、見逃されます。
+ `StartTimeOffset=180, EndTimeOffset=120` — ウィンドウ [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)」を参照してください。