ログアラーム

ログアラームは、スケジュールされたクエリを使用してスケジュールに従って実行される CloudWatch Logs Insights クエリの結果をモニタリングします。アラームは集計式をクエリ結果に適用して数値を生成し、その集計値が設定されたしきい値を超えると、アラームは ALARM 状態に移行し、設定されたアクションを実行します。

ログアラームは、中間ステップとしてメトリクスフィルターを必要とするメトリクスアラームとは異なり、アドホック分析に使用するのと同じ Logs Insights クエリ言語を使用してログデータを直接評価します。

ログアラームの仕組み

次の手順はログアラームの仕組みについて説明したものです。

ログアラームの作成方法については、「ログアラームの作成」を参照してください。

マネージドのスケジュールされたクエリのライフサイクル

ログアラームを作成すると、CloudWatch は、指定されたスケジュールでクエリを実行する AWS マネージドのスケジュールされたクエリを自動的に作成します。スケジュールされたクエリを個別に作成する必要はありません。

AWS マネージドのスケジュールされたクエリには次の特性があります。

ログアラームの設定

ログアラームは、次のパラメータで設定されます。

パラメータの完全なリストと作成手順については、ログアラームの作成 を参照してください。

ログクエリ

ログアラームクエリは、評価するログデータを選択してフィルタリングする CloudWatch Logs Insights クエリです。このクエリは、StartTimeOffset および EndTimeOffset で定義された時間範囲にわたって、LogGroupIdentifiers で指定されたロググループで実行されます。

このクエリは CloudWatch Logs Insights のクエリ構文を使用します。ログアラームの効率的なクエリの記述に関するガイドラインについては、「ベストプラクティスとトラブルシューティング」を参照してください。

集計式

集計式は、CloudWatch がクエリ結果をしきい値評価の数値にまとめる方法を定義します。この式は、CloudWatch Logs Insights の stats コマンドと同じ構文を使用します。

集計式の構文は次のとおりです。

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

指定できる集計式は 1 つだけです。次の表に、サポートされている集計関数を示します。

bin() 関数は、集計式の by 句ではサポートされていません。ただし、クエリ文字列自体で bin() を使用できます。

マルチコントリビューターアラーム

集計式に by 句を含めると、アラームはフィールド値の一意の各組み合わせ (「コントリビューター」と呼ばれる) を個別に評価します。いずれかのコントリビューターがしきい値を超えた場合、アラームは ALARM 状態に移行します。

たとえば、次の式はサービス名でエラー数をグループ化します。

count(*) by serviceName

serviceName の一意の各値は、しきい値に対して個別に評価されます。いずれかのサービスが N 回のクエリ実行のうちしきい値を M 回超えると、アラームは ALARM 状態になります。

マルチコントリビューターアラームには次の制限が適用されます。

デフォルトでは、コントリビューターはアルファベット順にソートされ、クエリの実行ごとに最初の 500 個のみが返されます。あるいは、コントリビューターを集計値でソートする場合は、集計式で | sort asc または | sort desc を指定します (例: avg(latency) by serviceName | sort desc)。値ベースのソートでは、合計数が 500 を超えると、最も重要なコントリビューターが最初に評価されます。

マルチコントリビューターアラームの場合、Amazon SNS と Lambda アクションはコントリビューターレベルで実行されます (違反しているコントリビューターごとに 1 回)。Systems Manager の OpsItem アクションはアラームレベルで実行されます。

コントリビューターがクエリ結果から消えた場合 (エフェメラルリソースが終了した場合など)、そのコントリビューターは、欠落しているデータ処理設定に関係なく OK 状態に移行します。

欠損データ処理

欠落データは、スケジュールされたクエリ実行がしきい値に対して評価できる値を生成しない場合に発生します。次の場合に発生:

ログが存在しない — ロググループにクエリ時間範囲内のログイベントが含まれていません。

クエリが該当する結果を返さない — ログは存在しますが、集計式は値を生成できません。これは次のような場合に起こります。

空の結果セットの count(*) では、有効なデータポイントで欠落として扱われない 0 が返されることに注意してください。

アラームが TreatMissingData パラメータを使用して欠落データを処理する方法を設定できます。次の表では利用可能なオプションを説明しています。

評価ステータス

ログアラームは、標準の OK、ALARM、INSUFFICIENT_DATA 状態に加えて、EvaluationState フィールドで次の評価状態をレポートできます。これらの状態は、アラームが現在の状態にある理由に関する追加のコンテキストを示します。

アラームの更新

ログアラームのクエリ、集計式、スケジュール、またはロググループを更新すると、十分な新しいデータポイントが収集されるまで、アラームは INSUFFICIENT_DATA に移行します。しきい値または M-out-of-N 値を変更しても、このリセットはトリガーされません。

アクションおよび通知

ログアラームでは以下のアクションがサポートされています。

アクションサポートマトリックスの詳細については、「アラームアクション」を参照してください。

ログアラームの状態が移行すると、アクション通知には次の情報が含まれます。

次の例は、単一値ログアラーム (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 で、ログ行は含まれません。

ログ行を含めるには、ログ行ロールに logs:GetQueryResults アクセス許可が必要です。通知に含まれるログ行の数は、リクエストされた数、使用可能な合計結果、および Amazon SNS ペイロードサイズ制限によって制限されます。

ベストプラクティスとトラブルシューティング

ベストプラクティス

クエリの最適化

スケジュール計画

しきい値の調整

マルチコントリビューター設計

トラブルシューティング

アラームが INSUFFICIENT_DATA にとどまる

アラームに EVALUATION_ERROR と表示される

これはクライアント設定の問題を示しています。詳細については、StateReason フィールドを確認してください。一般的な原因:

アラームに EVALUATION_FAILURE と表示される

これは一時的な CloudWatch サービスの問題を示しています。問題が解決すると、アラームは自動的に復旧します。数分経っても解決しない場合は、CloudWatch サービスヘルスダッシュボードを確認してください。

アラームに PARTIAL_DATA と表示される

クエリは最大 500 個のコントリビューターグループを返しましたが、それ以上の数のグループが一致しています。アラームは使用可能なコントリビューターを評価しますが、結果は不完全である可能性があります。クエリを絞り込むか、BY 句フィールドの数を減らすことを検討してください。

通知にログ行が表示されない

クエリの最適化、モニタリング、認可に関するその他のベストプラクティスについては、「Amazon CloudWatch Logs ユーザーガイド」の「スケジュールされたクエリのベストプラクティス」を参照してください。