各Eventに対するルールを設定しておくことで、PagerDutyでEventを受け取った際にその処理を自動化することができます。この記事ではEvent Orshestrationを利用して、どのようなルールが設定できるのか説明します。

本記事で説明する機能の一部は、AIOps等の追加ライセンスがないと利用できないものがあります。詳細はナレッジベース:Event Orchestrationを参照ください。

Event Orchestrationとは

監視ツール等から送られるEventをPagerDutyで受け取り、その処理を行うための機能群になります。以下4つの機能で構成されています:

Integrations: Eventの受け取り口(Integration-KeyとEmailアドレス)を作成します。
Global Orchestration Rules: Eventに関するルールを定義し、自動処理します。
Service Routes (Routing Rules): Eventを各Serviceに紐づけます。
Service Orchestration Rules: Eventに関するルールを定義し、自動処理します。

1.Integrationsと3.Service Routesに関しては、検知編の記事を参照ください。
この記事では、2.Global Orchestration Rules と 4.Service Orchestration Rulesについて説明します。

Global Orchestraion Rules と Service Orchestration Rules

Global Orchestration Rulesは、複数のServiceで共通の処理を行う際に利用します。
Routing RulesでEventを各Serviceに振り分ける前に適用されるので、1つのルールで全てのEventを対象に処理を行うことができます。

Service Orchestration Rulesは、各Serviceの固有の処理を定義します。
Service Orchestration Ruleは、Service Integrationで受信したEventにも適用されます。

なお、最後に評価されたルールが優先されるため、同種のActionがGlobal Orchestration RulesとService Orchestration Rulesの両方で定義されていた場合、後者のService Orchestrations Rulesで上書きされます。

Event Rules

Global Orchestraion Rules と Service Orchestration Rulesは、複数のEvent Ruleで構成されています。下図の四角いブロックがEvent Ruleになります。

各Event Ruleには、Conditions (Eventに関する条件) と Actions (ConditionsにマッチしたEventに対して行う処理) を設定します。

各ルールが評価される順序:

Event Ruleの評価は1からスタートし、ルールにマッチした場合は右方向、マッチしなかった場合は下方向のルールの評価に移ります。
あるEventが1のConditionsにマッチした場合、1のActionsを実行し、(右側にルールがないため)処理は終了します。
あるEventが1のConditionsにマッチしない場合、下方向へ2の評価に進みます。
- 2にマッチした場合は2のActionsを実行後、右方向へ2Aの評価に進みます。
  - 2Aにマッチしなかった場合、2Bの評価に進みます。

Conditions

Eventに関する条件を設定します。

利用可能なConditions:

If events match certain conditions: Eventに含まれるデータ(KeyとValue)に関する条件
On a recurring weekly schedule: 週次の定期的なスケジュール
During a scheduled date range: 特定の期間を日時で指定
Depends on event frequency: Eventの受信頻度 (例: 5分間に10 Event以上)

これらをAND¹/ORで組み合わせ、対象とするEventを柔軟に指定することが可能です。

Integrationに事前にEventを送っておくと、送られたEventに含まれるデータを参照しながら条件を設定することができます。(Event内のデータをクリックすると、クリックした箇所のKeyとValueがセットされます。)

Actions

ConditionsにマッチしたEventに対して、行う処理を設定します。

Incident Data　- Basic Event
インシデントに関するデータを変更できます。

Suppress incident...: インシデントを起票せず、通知も行いません。
Pause notifications...: 指定した秒数、通知を一時停止します。Auto Pauseを上書きできます。
Set incident priority...: インシデントのPriorityを設定・変更します。
Add incident note: インシデントにNotes欄に手順書へのリンク等、任意のコメントを追加します。

Incident Data - Event Fields
Eventに含まれるデータを編集したり、追加することができます。

上記の例では、インシデントのタイトル(Summary)を変更しています。

変更を行うEvent Fieldを選択し、値を指定します。
利用できる値は、以下です:

Eventに含まれるフィールド(CEF) - 例: event.class, event.custom_details.plain_body
Eventに含まれるフィールド(CEF変換前) - 例: raw_event.client,raw_event.description
次項のVariablesで作成した変数 - 例: variables.MessageID, variables.Location
任意の文字列 - 例: [緊急], Infraチーム

Incident Data - Custom Fields
Custom Fieldsに値を追加・変更します。
値の指定方法は、Variables, Event Fields, または静的テキストが利用できます。

Custom Fieldsは、インシデント詳細画面内で共有Fieldsの下に表示されます。

Variables
前述のEvent Fieldsで利用する変数を定義できます。

上記の例では、Emailで受信したEventの本文から、メッセージIDの値を正規表現で抽出し、MessageIDという変数を定義しています。

Alert Data
アラートに関するデータを変更できます。

Set alert severity to...: Eventに含まれるpayload.severityの値を上書きします。
値はcritical, error, warning or infoの4つで、前者2つはHigh-Urgency, 後者2つはLow-Urgencyの通知ルールが選択されます。²

Override the given event_action behavior
- Always trigger an alert: event_actionの値を無視して、Eventをtriggerとして扱います。
- Always resolve an alert: event_actionの値を無視して、Eventをresolveとして扱います。*

*: ユースケースとしては、Emailでトリガーされたアラートを、後続のEmailを受信時に自動復旧させる場合があります。
Emailはevent_actionの情報を持たないため、デフォルトでは全てtriggerとして扱われます。本文に"復旧"の文字列が含まれたメールを受信した際に、resolveとして扱うルールを設定すると、"復旧"のメールを受信した際に、アラートの状態をResolveに変更することができます。

Automation - Webhooks
PagerDuty外の仕組みと連携し、自動化を行うことができます。

Enable webhook to specified endpoint for these incidents: チェックを入れると、Webhookの送信を有効化します。
- Must be maually triggered through incident dropdown: インシデント詳細画面のドロップダウンメニューにボタンを追加し、担当者がボタンを押すとWebhookを送信します。
- Automatically triggered on incident creation: インシデント起票時にWebhookを自動送信します。
Name: ボタン名(実行される処理の説明)
API Endpoint: Webhookの送信先URL
Headers: WebhookのHTTPヘッダーに含める情報を指定
JSON Body Fields: WebhookのBodyに含める情報を指定

ユースケースとしては、インシデント起票時にWebhookをAWS EventBridgeに送り、LambdaやStep Functionsと連携してEC2インスタンスの再起動や、ステータスページ更新を自動化するといったものがあります。

実行結果などの情報をPagerDutyに戻したい場合は、PagerDuty REST APIを利用してPagerDutyに情報を渡す仕組みを送信先で構築する必要があります。

Automation - Automation Actions
PagerDutyが提供する自動化の仕組み(Automation ActionsやRunbook Automation)と連携し、Event-Drivenでジョブを実行することができます。

Automation Actionsで作成したジョブを選択できます。
自動診断や自動修復、復旧後の正常性確認等、インシデント対応時に必要な作業を自動化することで、ミスのない迅速な対応と担当者の負担軽減が可能です。

進捗や実行結果等の情報をPagerDutyに戻す仕組みが用意されているため、PagerDutyやSlack上で実行ログや結果を確認しながら、迅速に対応を継続できます。

Event Rulesの設定例

CEF(Common Event Format)を利用して条件を指定する

PagerDutyでは標準のEventフォーマット(共通イベントフォーマット PD-CEF)が定義されています。
PagerDutyと連携可能な監視ツール等は、このフォーマットでEvent情報を送ります。ここではCEFの構造と、CEFを利用したEvent Rule Conditionの設定例を説明します。

以下はEvent APIv2で利用するCEFの例です:

{
  "payload": {
    "summary": "[Payment Process] ES Cluster Avg Max Load is > 2.5",
    "timestamp": "{{timestamp}}",
    "source": "aws:elasticache:us-east-1:852511987:cluster/api-stats-prod-003",
    "severity": "error",
    "component": "LOAD_AVERAGE",
    "group": "Domainname:prod-es-7-1-v4, monitor, terraform:true",
    "class": "deploy",
    "custom_details": {
        "body": "aws.es.os_1min_load over prod-es-7-1-v4 was > 2.5 on average",
        "Metric value": 2.51
    }
  },
  "routing_key": "(省略)",
  "dedup_key": "central-region-dc-01:852559987:005",
  "event_action": "trigger"
}

必須フィールド:

summary: Eventのタイトル(アラートとインシデントのタイトルに引き継がれる)
severity: Eventの深刻度を4段階で指定 (critical, error, warning, or info)
source: 影響を受けるシステム(hostnameやFQDN)
routing_key: Integrationで発行したIntegration-Key(32文字)
event_action: Eventのタイプ(trigger, acknowledge, or resolve)

その他:

dedup_key: アラートの重複排除キー。同じdedup_keyを持つEventは、1つのアラートに紐付けられる。値の指定がなければ、Event受信時にPagerDutyが自動付与。
custom_details: 標準フィールドにない付加情報はこの下に追加される。

例1: Eventのタイトル(summary)を参照して文字列 [Payment Process] の部分一致を指定

例2: Custom Details内のMetric valueフィールドを参照して、正規表現で3.00以下の値を指定

Emailから正規表現で情報を抽出し、Custom Detailsに格納する

Emailでは件名や本文に複数のパラメータが含まれていることがあります。Global OrchestrationでIncident Data/Event Fieldsを利用し、各パラメータをCustom Detailsに書き出しておくと、Service Orchestrationでの条件指定が簡単になります。

Emailで利用可能な主なFieldsは以下です:

event.custom_details.subject: 件名
event.custom_details.plain_body: 本文
event.custom_details.from: 送信元メールアドレス

例1: メール本文から情報を抽出し、Custom Detailsに追加
Variablesで、メール本文から情報を抽出し、変数(Server,Severity)を定義

Variablesで定義した変数を利用して、Incident Data/Event Fieldsで作成した変数をCustom Detailsに追加

PagerDutyに送信するEmailの例:

Subject: High API auth errors: 2% - prod-apigw-d01
To: (省略)
From: (省略)
cc: 

High API auth errors

Timestamp: 2023-12-30T04:24:15.041Z

Event ID: ABF023995
Auth Error Rate: 27
Server: prod-apigw-d01
Priority: 1

Event: trigger Severity: warning Source: prod-apigw-d01 Category: API Gateway User: N/A

Custom Detailsが追加されたアラートの例:

Custom Detailsに新たにSeverityとServerのFieldが追加されました。
Global Orchestrationでこのような処理をしておくと、以降のService RoutingやService Orchestrationでは、これらのField(event.custom_details.Server, event.custom_details.Severity)を利用することができます。

Emailで受信したアラートをLow-Urgencyとして扱う

EmailではSeverityに相当するフィールドをがないため、デフォルトでは全てHigh-Urgencyとして扱われます。通知レベルをLow-Urgencyに落としたい場合は、ServiceでDynamic Notificationを有効にした上で、Event OrchestrationでSeverityを変更します。

例: Emailに対する条件

上の条件では、1つ前の例で作成した event.custom_details.Severity を利用しています。
下の条件では、メール本文を参照し、正規表現で指定しています。

例: Severityを変更し、通知レベルを Low-Urgency に変更
Alert DataでSeverityを info または warning にすると、Low-Urgencyの通知ルールが利用されます。

件名が同じEmailを異なるアラートとして扱う

Emailでは件名をdedup_keyとして利用します。そのため、件名が同じEventは同じアラートに紐づくものと判断され、1つのアラートにまとめられます。
件名が同じEventを異なるアラートに分けたい場合は、Incident Data/Event Fieldsでdedup_keyを変更します。

例: dedup_key とアラートのタイトルを変更

上の例では、dedup_keyとsummaryにVariablesで定義した変数:Serverの値を追加しています。
これにより、メール件名が同一でもServerの値が異なれば、別々のアラートとして扱われます。
また、各アラートのタイトルにもServerの値が表示されます。

例: 件名が同一でServerが異なるEventを送信した結果

FAQ

Emailでイベントを送っていますが、Event Ruleが適用されません。

Global Integrationを利用して、Email連携を行っているか確認ください。
Global Orchestration RulesやService Orchestration Rulesで制御するためには、Event OrchestrationのIntegrationsで発行したEmailアドレス宛にイベントを送る必要があります。

Service Integrationで送信されたEmailイベントは、Email Filter機能で制御することができます。本機能については今後拡張予定がないため、前述のGlobal IntegrationとGlobal Orchestration/Service Orchestrationの利用を推奨します。

正規表現にマッチしない

こちらの記事を参照ください。

PagerDuty の Event Orchestration の正規表現でつまずいた

PagerDuty設定ガイド目次

検知編 | トリアージ編 | 動員編 | 解決編 | 学習編

一次対応を自動化する
Alert Groupingでアラートノイズを削減する
Auto Pauseで一過性アラートの通知を削減する
[Event Orchestrationでアラートへの対処を自動化する] << イマココ
診断や復旧作業を自動化する

参考リソース

2-4のConditionを選択した場合、GUIではAND条件が設定できません。しかし、PCLを利用すれば、AND条件を設定することが可能です。 ↩
Dynamic Notificationが有効になっている場合。デフォルトでは、severityの値に関わらずHigh-Urgencyとして扱います。 ↩