ログベースのアラートの管理

ログベースのアラートを使用すると、含まれたログに特定のメッセージが表示されるたびに通知できます。たとえば、監査ログで特定のデータアクセス メッセージが記録されたことを知りたい場合は、メッセージと一致するログベースのアラートを作成し、それが発生したときに通知できます。このドキュメントでは、Google Cloud Console と Cloud Monitoring API を使用して、次のことを行う方法について説明します。

  • ログベースのアラートを作成してテストする。
  • ログベースのアラートを編集する。
  • ログベースのアラートを削除する。

始める前に

アラートの比較を確認して、ログベースのアラートがログのデータに適しているかどうかを確認します。例:

  • ログベースのアラートは、除外されたログに対しては機能しません。

  • ログベースのアラートを使用して、ログからカウントを取得することはできません。カウントを取得するには、代わりにログベースの指標を使用する必要があります。

ログベースのアラートを作成して管理するには、ログベースのアラートの権限で説明されている承認が必要です。

ログベースのアラートを作成する(ログ エクスプローラ)

ログベースのアラートは、Google Cloud Console の [ログ エクスプローラ] ページで作成するか、Monitoring API を使用して作成できます。このセクションでは、ログ エクスプローラを使用してログベースのアラートを作成する方法について説明します。Monitoring API を使用してログベースのアラートを作成するには、ログベースのアラートを作成する(Monitoring API)をご覧ください。

ログ エクスプローラのインターフェースでは、次の手順でログベースのアラートの作成、編集が可能です。

  • アラートの名前と説明を入力します。
  • 通知を受け取るログを選択します。
  • 通知の間隔を設定します。
  • インシデントの自動クローズまでの時間を設定します。
  • 通知先のユーザーを指定します。

たとえば、アプリケーションがネットワーク アドレスを変更したときに、重大度が NOTICEsyslog ログエントリを書き込むアプリケーションがあるとします。ネットワーク アドレス変更のログエントリには、次のような JSON ペイロードが含まれています。

"jsonPayload": {
  "type": "Configuration change",
  "action": "Set network address",
  "result": "IP_ADDRESS",
}

無効な IPv4 アドレスが、重大度が NOTICEsyslog のログエントリの jsonPayload.result フィールドに表示された場合に通知するログベースの指標を作成します。

ログベースのアラートを作成する手順は次のとおりです。

  1. Cloud Console で [Logging] を選択し、[ログ エクスプローラ] を選択します。

    ログ エクスプローラに移動

  2. [クエリ] ペインを使用して、ログベース アラートで使用するメッセージに一致するクエリを作成します。

    たとえば、syslog ログの中の重大度が NOTICE のログエントリのうち、JSON ペイロードに無効な IP アドレスがあるものを見つけるには、次のクエリを使用します。

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    [クエリ結果] ペインで [クエリを実行] を使用してクエリを検証します。

  3. [クエリ結果] ペインの上部にある、 [アラートを作成] をクリックします。ウィンドウの幅が狭い場合、[アラートを作成] オプションは [その他の操作] メニューに表示されます。

  4. [アラートの詳細] ペインで、アラートの名前と説明を入力します。

    1. [アラート名] フィールドにアラートの名前を入力します。たとえば、「ネットワーク アドレス: 無効な IPv4 値」などです。

    2. このアラートの説明を入力します。通知の受信者が問題を診断する際に有用な情報を表示することもできます。 次の文字列では、アラートの理由を要約しています。

      Log-based alert in project ${project} detected an invalid IPv4 value.
      

      このフィールドの内容のフォーマットと調整の詳細については、ドキュメント テンプレートでマークダウンと変数を使用するをご覧ください。

  5. 次のステップに進むには、[次へ] をクリックします。

  6. [アラートに含めるログを選択] ペインで、[ログをプレビュー] をクリックしてクエリと結果を確認します。

    ログ エクスプローラの [クエリ] ペインでクエリを作成することをおすすめします。[クエリ] ペインで作成したクエリもこのペインに表示されます。次に例を示します。

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    必要に応じて、このペインでクエリを編集できます。クエリを編集する場合は、[ログをプレビュー] をクリックして結果を確認します。

  7. [次へ] をクリックします。

  8. 通知間の最小時間を選択します。この値により、このアラートが複数回トリガーされた場合に受信する通知の数を制御できます。この例では、オプションから [5 minute] を選択します。

    インシデントの自動クローズ期間はデフォルト値のまま残すことも、メニューで別のオプションを選択して異なる値に設定することもできます。

  9. [次へ] をクリックします。

  10. アラートの通知チャネルを 1 つ以上選択します。この例では、メール通知チャネルを選択します。

    すでにメール通知チャンネルを構成している場合は、リストからそれを選択できます。そうでない場合は、[通知チャンネルを管理] をクリックしてメールチャンネルを追加します。通知チャンネルの作成方法については、通知チャンネルの管理をご覧ください。

  11. [保存] をクリックします。

これで、ログベースのアラートをテストできるようになりました。

ログベースのアラートの例をテストする

作成したアラートをテストするには、クエリに一致するログエントリを手動で記述します。ログエントリを記述するには、次のようにします。

  1. 次のログエントリを、PROJECT_ID 変数はプロジェクト ID に変更して構成します。

    {
      "entries": [
      {
        "logName": "projects/PROJECT_ID/logs/syslog",
        "jsonPayload": {
          "type": "Configuration change",
          "action": "Set network address",
          "result": "999.027.405.1",
        },
        "severity": "NOTICE",
        "resource": {
          "type": "generic_task",
          "labels" : {
            "project_id": "PROJECT_ID",
            "location": "us-east1",
            "namespace": "fake-task-2",
            "job": "write-log-entry",
            "task_id": "11",
          },
        },
      ],
    }
    
  2. logEntries.write リファレンス ページに移動するか、次のボタンをクリックします。

    logEntries.write に移動

  3. 構成したログエントリをコピーします。

  4. [この API を試す] ペインで、次の手順を行います。

    1. API Explorer の [Request body] フィールドの内容を前の手順でコピーしたログエントリに置き換えます。

    2. [実行] をクリックします。入力を求めるメッセージが表示されたら、認証フローに従います。

      logEntries.write の呼び出しが成功すると、HTTP 200 レスポンス コードと空のレスポンスの本文 {} が返されます。API Explorer の詳細については、Monitoring のドキュメントの API Explorer の使用をご覧ください。 API Explorer の動作は Logging API と同じです。

ログエントリは、次の方法でアラートに指定されたフィルタと一致します。

  • logName 値はクラウド プロジェクトの syslog ログを指定します。
  • このログエントリの severity 値は NOTICE です。
  • jsonPayload.result 値が有効な IPv4 アドレスではありません。

ログエントリを書き込むと、次のシーケンスが発生します。

  • 新しいログエントリがログ エクスプローラに表示され、アラートがトリガーされます。
  • インシデントが Cloud Monitoring で開かれます。
  • インシデントの通知が届きます。メール通知チャネルを構成した場合、通知は次のスクリーンショットのようになります。

    ログベースのアラートの例はメール通知になります。

メール内の [インシデントを表示] をクリックすると、Cloud Monitoring でインシデントを確認できます。インシデントの詳細については、ログベースのアラートのインシデントの管理をご覧ください。

その他のシナリオ: 監査ログに関するアラート

ログベースのアラートの作成の例は人為的なもので、通常、アラートを作成してから、アラートをトリガーするログエントリを手動で作成することはありません。たいていログエントリは、アプリケーションか、他のサービスによって書き込まれます。ただし、ログエントリの発生元は重要ではありません。ログベースのアラートでは、ログエントリの選択に使用するクエリが重要です。

以降のセクションでは、ログベースの指標の現実的なシナリオを、監査ログの内容に基づいて説明します。各シナリオでは、必要な監査ログエントリを切り分けるクエリを作成する方法を説明します。それ以外の場合、ログベースのアラートの作成手順は、ログベースのアラートの作成と同じです。

シークレットの人的アクセスに関するアラート

たとえば、プロジェクト内でシークレットを Secret Manager に保存し、一部のシークレットがサービス アカウント専用で使用されるとします。特殊な状況を除き、人間のユーザーがこれらのシークレットにアクセスすることはありません。

Secret Manager の監査ロギングが有効になっていると、シークレットへのアクセスが試されるたびに、監査ログエントリが作成されます。各エントリには、シークレットの名前と呼び出し元の ID が含まれています。

人間のユーザーがシークレットにアクセスしたときに通知されるログベースのアラートを作成できます。

以下は、Secret Manager によって書き込まれた監査ログエントリの抜粋です。この抜粋は、ログベースのアラートのクエリの作成に役立つフィールドを示しています。

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "serviceName": "secretmanager.googleapis.com",
    "methodName": "google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion",
    "authenticationInfo": {
      "principalEmail": "my-svc-account@PROJECT_ID.iam.gserviceaccount.com",
      "serviceAccountDelegationInfo": [],
      "principalSubject": "serviceAccount:my-svc-account@PROJECT_ID.iam.gserviceaccount.com"
    },
    ...
  },
  ...
}

次の protoPayload サブフィールドが、特に重要です。

  • @type: このログエントリが監査ログエントリであることを示します。
  • serviceName: 監査ログエントリを書き込んだサービスを記録します。このフィールドは、Secret Manager によって書き込まれたエントリを識別するために使用します。
  • methodName: この監査ログエントリが書き込まれたメソッドを識別します。このフィールドを使用して、このエントリが作成されるアクションを識別します。この例では、AccessSecretVersion メソッドです。
  • authenticationInfo.principalEmail: メソッドを呼び出したアカウントを methodName フィールドに記録します。このフィールドの想定値はサービス アカウントであり、末尾は gserviceaccount.com です。

人間のユーザーによる Secret アクセスのログエントリを見つけるには、Secret Manager によって書き込まれた監査ログエントリを探します。gserviceaccount.com で終わるプリンシパルによって AccessSecretVersion メソッドが呼び出されたログエントリを確認する必要があります。次のクエリは、これらのログエントリを分離します。

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "secretmanager.googleapis.com"
protoPayload.methodName =~ "AccessSecretVersion$"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

シークレットの人間によるアクセスに関するログベースのアラートを作成するには、[アラートに含めるログの選択] ペインでこのクエリを使用します。

復号イベントに関するアラート

前の例の分析は、他のサービスにも適用できます。たとえば、Cloud Key Management Service を使用して機密データを暗号化および復号する場合、Cloud KMS によって生成された監査ログを使用して、人間のユーザーによる値の復号を検出します。

人間のユーザーが復号したことを示すログエントリを見つけるには、Cloud KMS によって書き込まれた監査ログエントリを探します。見つける必要があるログエントリは、末尾が gserviceaccount.com(サービス アカウント)以外のプリンシパルが呼び出した Decrypt メソッドのログエントリです。次のクエリは、これらのログエントリを分離します。

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "cloudkms.googleapis.com"
protoPayload.methodName = "Decrypt"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

人間のユーザーが行った復号に対するログベースのアラートを作成するには、[アラートに含めるログを選択] ペインでこのクエリを使用します。

Monitoring でログベースのアラートを管理する

Cloud Console for Monitoring または Monitoring API を使用して、ログベースのアラートの表示、編集、削除を行うことができます。このドキュメントでは、Cloud Console を使用してアラート ポリシーを管理する方法について説明します。Monitoring API を使用してアラート ポリシーを管理する方法については、API によるアラート ポリシーの管理をご覧ください。

Google Cloud プロジェクトのすべてのアラート ポリシーを一覧表示するには、次のいずれかを行います。

  • Logging から移動するには:

    1. Cloud Console で [Logging] を選択し、[ログ エクスプローラ] を選択します。

      ログ エクスプローラに移動

    2. [クエリ結果] ペインの [その他の操作] メニューで、[アラートの管理] を選択します。

  • Monitoring から移動するには:

    1. Cloud Console で、[Monitoring] を選択します。

      [Monitoring] に移動

    2. [アラート] を選択します。

    3. ポリシーの部分的なリストが [Policies] ペインに表示されます。すべてのポリシーを表示してフィルタを有効にするには、[See all policies] をクリックします。

どちらの操作でも Monitoring の [ポリシー] ページが表示され、クラウド プロジェクトのすべてのアラート ポリシーが一覧表示されます。

一覧表示されるアラート ポリシーを制限するには、フィルタを追加します。各フィルタは、名前と値で構成されています。 たとえば、値をポリシー名の完全一致か、部分一致に設定できます。一致の判定で、大文字と小文字は区別されません。複数のフィルタを指定すると、OR フィルタを挿入しない限り、暗黙的に論理 AND で結合されます。次のスクリーンショットは、2021 年 1 月 1 日以降に作成された、現在有効なアラート ポリシーを示しています。

2021 年 1 月 1 日以降に作成された有効なアラート ポリシーのリスト。

[ポリシー] ページでは、アラート ポリシーを編集、削除、コピー、有効化、無効化できます。

  • ポリシーを編集またはコピーするには、 [その他のオプション] をクリックして、対応するオプションを選択します。ポリシーの編集方法とコピー方法は、ログベースのアラートを作成する方法と似ています。フィールドの値を変更したり、場合によっては削除したりできます。完了したら、[Save] をクリックします。

    ログベースのアラート ポリシーは、ポリシーのリストの名前をクリックして編集することもできます。

  • ポリシーを削除するには、[その他のオプション] をクリックし、[削除] を選択します。確認ダイアログで [削除] を選択します。

  • アラート ポリシーを有効または無効にするには、[有効] 項目下にある切り替えボタンをクリックします。

ログベースのアラートを作成する(Monitoring API)

ログベースのアラートは、Monitoring API を使用して作成できます。Monitoring API には、Google Cloud Console でログ エクスプローラを使用する場合と同じ情報を渡します。

  • アラートの名前と説明。
  • 通知を受け取るログ。
  • 通知の間隔。
  • インシデントの自動クローズまでの時間。
  • 通知するユーザ。

Monitoring API を使用してアラート ポリシーを作成するには、AlertPolicy オブジェクトを作成し、alertPolicies.create メソッドに送信します。

Monitoring API を使用する前に、API を有効にし、その使用を承認する必要があります。詳細については、以下のドキュメントをご覧ください。

アラート ポリシーの構造

Monitoring API では、AlertPolicy 構造を使用してアラート ポリシーを表します。AlertPolicy 構造には、アラートをトリガーする条件の説明など、いくつかの埋め込み構造があります。ログベースのアラート ポリシーは、以下の点で指標ベースのアラート ポリシーと異なります。

  • 条件を記述するには、LogMatch 条件タイプを使用します。指標ベースのアラート ポリシーでは、異なる条件タイプが使用されます。
  • ログベースのアラート ポリシーに含めることができる条件は 1 つのみです。
  • 通知から自動インシデント終了までの時間は、AlertStrategy 構造体を追加して指定します。指標ベースのアラート ポリシーには、通知間の時間は含まれません。

このセクションでは、ログベースのアラート ポリシーの作成方法について説明します。これらのポリシーは、使用する条件のタイプにおいて、指標ベースのアラート ポリシーと異なります。ログベースのアラートの場合、条件タイプは LogMatch です。Monitoring API を使用してアラート ポリシーを管理する場合、指標とログベースの指標のポリシーの一覧表示、編集、削除の方法に違いはありません。API によるアラート ポリシーの管理では、Monitoring API を使用してアラート ポリシーを作成、一覧表示、編集、削除する方法について説明しています。

アラート ポリシーを設計する

ログベースのアラートの作成(ログ エクスプローラ)では、重大度が NOTICEsyslog のログエントリの jsonPayload.result フィールドに無効な IPv4 アドレスが発生したときに通知するログベースのアラートを作成します。

Monitoring API を使用して同じログベースのアラートを作成するには、次の JSON 構造のような AlertPolicy オブジェクトを作成します。

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alert in project ${project} detected an invalid IPv4 value.",
    "mimeType": "text/markdown"
  },

  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr (API)",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\") severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",

  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    },
    "autoClose": "604800s",
  },

  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

この JSON コードは、ログ エクスプローラを使用したログベース アラートの作成で指定するものと同じ情報を指定します。次のセクションでは、この AlertPolicy 構造の内容を、ログ エクスプローラを使用してログベースのアラートを作成する手順にマッピングします。conditionMatchedLog フィールドの値は LogMatch 構造です。

名前と説明を入力する

アラート ポリシーには、応答者に役立つ通知を提供する表示名と関連するドキュメントがあります。ログ エクスプローラでは、これらの項目を、アラート名アラートの説明と呼んでいます。これらの値は、AlertPolicy 構造で次のように表現します。

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alert in project ${project} detected an invalid IPv4 value.",
    "mimeType": "text/markdown"
  },
  ...
}

この例では、Cloud Console でポリシーのリストを表示するときに 2 つのサンプル ポリシーが区別できるように、displayName の値に「(API)」が含まれています。Monitoring の [ポリシー] ページには、表示名でポリシーが表示され、ポリシーが指標とログのどちらに基づくかが表示されます。詳細については、Monitoring でログベースのアラートを管理するをご覧ください。

documentation フィールドの content サブフィールドには、ログ エクスプローラを使用する際に指定する説明が含まれます。documentation フィールドの値を指定する場合、2 番目のサブフィールド mimeType は必須です。有効な値は "text/markdown" のみです。

通知を受け取るログを選択する

ログベースのアラート ポリシーには単一の条件があります。ログ エクスプローラの [アラート対象のログエントリを定義する] フィールドにクエリを指定するときに、条件を指定します。これらの値は、AlertPolicy 構造で次のように表現します。

{ ...
  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr (API)",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",
  ...
}

conditions フィールドは Condition 構造のリストを受け取りますが、ログベースの指標には条件が 1 つのみ必要です。各 Condition には、条件の表示名と説明があります。

  • displayName フィールドの値は、条件の簡単な説明です。ログ エクスプローラを使用してログベースのアラートを作成する場合、表示名は常に「Log match condition」です。Monitoring API を使用すると、より正確な表示名を指定できます。値を指定する必要があります。

  • conditionMatchedLog フィールドの値は LogMatch 構造であり、filter フィールドの値はログ エクスプローラで指定したクエリです。このクエリは JSON フィールドの値として提示されるため、クエリ全体が引用符で囲まれており、クエリ自体の引用符は \(バックスラッシュ)文字でエスケープする必要があります。

combiner フィールドの値は、指標ベースのアラート ポリシーで複数の条件の結果を組み合わせる方法を指定します。ログベースのアラートでは 1 つの条件のみを使用できます。また、combiner フィールドに値 "OR" を指定する必要があります。複数の条件を使用してログベースのアラートを作成することはできません。

通知と自動クローズの値を設定する

ログベースのアラートのアラート ポリシーは、通知間の最小時間を指定します。ログ エクスプローラでは、[通知間の時間] メニューから値を選択します。AlertPolicy 構成のこの値は、AlertStrategy 構造体に埋め込まれた NotificationRateLimit 構造体の period フィールドに、値(秒)を指定することで表します。

同様に、アラート ポリシーには、インシデントを自動的に終了するための期間が含まれます。デフォルト値は 7 日です。ログ エクスプローラでは、[インシデントの自動クローズ期間] メニューから別の値を選択できます。このオプションは、AlertStrategy API 構造の autoclose フィールドに対応します。このフィールドを使用する場合は、秒数を値を指定します。最小値は 1,800 秒(30 分)です。

{ ...
  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    },
    "autoClose": "604800s",
  },
  ...
}

この例の period フィールドの値 300s は、5 分に相当します。autoclose の値(604800s)は、7 日間に相当します。

通知するユーザーを指定する

アラート ポリシーには、通知チャネルのリストを含めることができます。ログ エクスプローラで、メニューからチャネルを選択します。これらの値を AlertPolicy 構造で表すには、構成済み NotificationChannel オブジェクトの 1 つ以上のリソース名のリストを指定します。

{ ...
  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

通知チャンネルを作成すると、リソース名が割り当てられます。リソース名を含む使用可能な通知チャンネルのリストを取得する方法については、Monitoring ドキュメントのチャンネルの取得をご覧ください。Cloud Console でチャンネル ID を取得することはできません。

Monitoring API にアラート ポリシーを送信する

Monitoring API を使用してアラート ポリシーを作成するには、AlertPolicy オブジェクトを作成し、それを alertPolicies.create メソッドに送信します。alertPolicies.create を呼び出すには、Google Cloud CLI を使用し、Monitoring API を直接呼び出します。

C#、Go、Java、Python、Ruby のクライアント ライブラリを使用して、ログベースのアラートを作成することもできます。他のクライアント ライブラリを使用できる場合もあります。言語のライブラリには、LogMatch 条件タイプが含まれている必要があります。

gcloud CLI を使用してアラート ポリシーを作成するには、次の手順を行います。

  1. アラート ポリシーの JSON 表現をテキスト ファイル(例: alert-invalid-ip.json)に追加します。

  2. 次のコマンドを使用して、この JSON ファイルを gcloud CLI に渡します。

    gcloud alpha monitoring policies create --policy-from-file="alert-invalid-ip.json"
    
  3. このコマンドが成功すると、新しいポリシーのリソース名が戻ります。次に例を示します。

    Created alert policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
    

alertPolicies.create を直接呼び出してアラート ポリシーを作成するには、次のように API Explorer ツールを使用します。

  1. alertPolicies.create リファレンス ページに移動します。

  2. [この API を試す] ペインで、次の手順を行います。

    1. name フィールドに次の値を入力します。

      projects/PROJECT_ID
      
    2. アラート ポリシーの JSON 表現をコピーし、API Explorer の [Request body] フィールドの内容を、コピーしたアラート ポリシーに置き換えます。

    3. [実行] をクリックします。

      alertPolicies.create の呼び出しが成功すると、HTTP 200 レスポンス コードと空のレスポンスの本文 {} が返されます。API Explorer の詳細については、Monitoring のドキュメントの API Explorer の使用をご覧ください。

Monitoring API を使用したアラート ポリシーの作成の詳細については、ポリシーの作成をご覧ください。このドキュメントの例では、指標ベースのアラート ポリシーの条件タイプが使用されていますが原理は同じです。

アラート ポリシーをテストする

新しいアラート ポリシーをテストするには、ログベースのサンプル アラートのテストと同じ手順を使用できます。