PagerDuty Event Orchestration で メールインシデントの重複排除を解除して同一件名のアラートを別インシデントで起票してみた

こんにちは。たかやまです。

PagerDutyでEvent Orchestrationを経由してメール通知をトリガーにインシデントを起票する構成を運用していたところ、本来は別々のアラートのはずのメールが1件のインシデントにまとめられてしまう事象に遭遇しました。

調べてみると、PagerDutyではEmail IntegrationとEvent Orchestrationで重複排除（deduplication）の挙動が異なることがわかりました。

これは意図した重複排除であれば問題ないですが、件名が同じでも内容が異なるアラート（対象ホストや発生時刻が違うだけなど）まで1つのインシデントに集約されてしまうと、個別に気づけないインシデントが埋もれてしまいます。

今回はEvent Orchestrationのdedup_keyをメールのMessage-IDで一意化することで、この意図しない集約を防ぐ方法を試してみます。

さきにまとめ

• メール経由のインシデントは既定で件名ベースの重複排除が働く
• Email Integration（サービス直付け）はUIのEmail Management Rulesで重複排除を制御できるが、Event Orchestration経由の場合はOrchestration側のdedup_keyが最終的な重複排除の挙動を決める
  • Event OrchestrationのdedupキーをメールのMessage-IDを使うのがおすすめ
• dedup_key 実装時の注意点
  • ハイフンを含むカスタムフィールド名はドット記法では参照できず、ブラケット記法が必要
  • dedup_keyは保存時に非ASCII文字（日本語など）が除去される
  • Orchestration変数が1つでも解決失敗すると、テンプレート全体が失敗してdedup_keyが既定値に戻る

Email IntegrationとEvent Orchestrationの重複処理の違い

まず前提として、PagerDutyでメールをトリガーにインシデントを起票する経路には大きく2パターンあります。

• サービスにEmail Integrationを直接紐付けて、そのサービスにメールを転送する
• Event Orchestrationのグローバルルーターやサービスオーケストレーションを経由してメールイベントをルーティングする

Email Integration Guide | PagerDuty

このどちらの経路を通るかで、重複排除の制御方法が変わってきます。

Email Integrationの場合

サービスに直接Email Integrationを設定している場合、Email Management Rulesという設定画面で重複排除の挙動を制御できます。

公式ドキュメントによると、デフォルトでは件名ベースに重複排除が行われます。

Emails with the same subject line will deduplicate. For example, if PagerDuty triggers an incident in response to an email with the subject "Host Down," subsequent emails with the same subject will not trigger a new incident.

日本語翻訳 :
同じ件名のメールは重複排除されます。例えば、PagerDutyが「Host Down」という件名のメールに対してインシデントを起票した場合、同じ件名のメールは新しいインシデントを起票しません。
https://support.pagerduty.com/main/docs/email-management-filters-and-rules

実際に起票してみると以下のようにメールの件名がAlert Keyとして設定され、Alert Logsから同名件名のメールがまとめられていることが確認できます。

Email Integrationでは「同一件名なら重複排除」ではなく「メールごとに別インシデントとして起票」というメール管理方法も選択できます。

こちらの設定で起票すると、件名とAlert Keyが別々に設定され、先ほどのインシデントとは別にインシデントとして起票されるようになります。

Email Integrationであれば、Integrationの設定上の機能だけで重複排除の粒度をある程度コントロールできます。

Event Orchestrationの場合

Event OrchestrationのIntegration経由でメールを受信している場合はEmail IntegrationのようにUI上で重複排除の粒度をコントロールできません。

ちなみにEvent OrchestrationのIntegration経由にメール通知した場合も、Email Integrationのデフォルトの重複排除の挙動と同じく、件名がAlert Keyとして設定されます。

では、Event Orchestration経由での重複排除の制御はどうするかというと、こちらは dedup_key を使って重複排除の挙動を制御します。

以下のドキュメントにある通り、Event Orchestration経由では dedup_key が一致するかどうかで重複排除の挙動が決まります。

Subsequent alerts with a matching dedup_key deduplicate into the same incident, and the new event is appended to the incident's Alerts log as an additional Trigger log entry.

日本語翻訳 :
dedup_keyが一致する後続のアラートは同じインシデントに重複排除され、新しいイベントはインシデントのAlertsログに追加のTriggerログエントリとして追記されます。
https://support.pagerduty.com/main/docs/event-management

では、 dedup_key に何を設定するかというところで、Email IntegrationのようにランダムなAlert KeyをEvent Orchestrationで付与するような機能はないため、メール情報から抽出した情報でdedup_keyを生成する必要があります。

Event Fields are only available for email events sent to Global Integrations. Users can extract data from the email event using regex matching into multiple rule variables. Currently, only Summary and Dedup_Key Common Event Fields can be replaced for email events.

日本語翻訳 :
Event Fieldsは、グローバルインテグレーション宛に送信されたメールイベントでのみ利用できます。ユーザーはregexマッチングを使ってメールイベントからデータを抽出し、複数のルール変数に格納できます。現時点では、メールイベントに対して置き換え可能なCommon Event FieldsはSummaryとDedup_Keyのみです。
https://support.pagerduty.com/main/docs/event-orchestration

ここからは、完全一意のdedup_keyを生成するためにメールのMessage-IDを使う方法を試してみます。

やってみる

dedup_keyをMessage-IDで一意化

すでに書いていますが、Event Orchestrationでユニークなdedup_keyを生成するならMessage-IDを使うのが良さそうです。

Message-IDはRFC 5322でグローバルに一意な識別子であることが求められているヘッダーなので、単体で十分な識別力を持ちます。

The "Message-ID:" field provides a unique message identifier that refers to a particular version of a particular message. [...] The message identifier (msg-id) itself MUST be a globally unique identifier for a message.

日本語翻訳 :
Message-IDフィールドは、特定のメッセージの特定のバージョンを参照する一意なメッセージ識別子を提供します。[中略]メッセージ識別子（msg-id）自体は、メッセージに対してグローバルに一意な識別子でなければなりません。
https://www.rfc-editor.org/rfc/rfc5322#section-3.6.4

Message-IDは、実際にPagerDutyへ届いたメールの生データから確認できます。インシデント詳細画面の「View Message」からログエントリを開き、「View Raw Message」をクリックすると、ヘッダーを含むメールの生データが表示されます。

この生データの中にあるMessage-IDヘッダーが、今回dedup_keyの対象にする値です。

メールの各フィールドは、Event Orchestrationからevent.custom_details.<フィールド名>という形式で参照できます。

Rules may be based on the content of an email by entering the email field as custom details in the event field event.custom_details.subject.

日本語翻訳 :
メールのフィールドをイベントフィールドのcustom details（例 event.custom_details.subject）として指定することで、メールの内容に基づいたルールを作成できます。
https://support.pagerduty.com/main/docs/event-orchestration

Message-IDの場合はヘッダー名がそのままmessage-idというキーになりますが、ハイフンを含むキー名はドット記法で参照できなかったため、検証ではevent.custom_details['message-id']というブラケット記法で参照しています。

Event OrchestrationではVariablesを使ってメール情報を抽出し、dedup_keyのテンプレートに組み込むことができます。

variablesでMessage-IDの抽出

Event Fieldsでdedup_keyにMessage-IDを組み込む

この状態で、Event OrchestrationのIntegrationにメール通知を実行すると以下のようにMessage-IDがdedup_keyとして設定されます。

Appendix dedup_keyの注意点

実装にあたって、以下3つの挙動にはまったので備忘として記載します。

1. ハイフンを含むフィールド名がドット記法で参照できない点

前述の通りMessage-IDはmessage-idというハイフン付きのキー名でcustom_detailsに格納されるため、Extraction Regexのpathをevent.custom_details.message-idのようにドット記法で指定すると、not a valid CEF v2 pathというエラーが返ってきます。

ハイフンのような特殊文字を含むキー名はドット記法でパースできないようで、event.custom_details['message-id']のようにブラケット記法で指定する必要がありました。

2. dedup_keyから非ASCII文字が除去される点

検証の過程でdedup_keyに日本語を含む値で重複排除の回避を試したところ、生成されたdedup_keyから日本語部分が消えていることに気づきました。

dedup_keyの保存時に非ASCII文字（日本語などのマルチバイト文字）が除去される仕様のようです。日本語件名のメールを扱う場合は、dedup_keyの一意性を件名だけに頼らず、Message-IDのようなASCIIで完結する識別子を必ず組み込んでおくのが安全です。

3. 変数解決に1つでも失敗するとテンプレート全体が失敗する点

Extractionのテンプレートに複数の変数を埋め込んでいる場合、そのうち1つでも解決に失敗すると、テンプレート全体が失敗してdedup_keyは既定値（件名のASCII部分のみ）にフォールバックします。

一部の変数だけ埋め込んで残りは空文字、という部分的な成功にはなりません。

例えばメール本文（plain_body）を複合キーの材料に使おうとしたケースでは、HTMLのみのメールで本文フィールドの値がnullになり、dedup_key生成そのものが失敗する事象がありました。フィールドが存在していても値がnullになるケースがあり、メールの形式によって挙動が変わる点は注意が必要です。

対策として、複合キーに使う変数は存在が保証されているフィールドのみに絞り込むのが安全です。

Message-IDはメールプロトコル上必須ヘッダーなので、この観点でも複合キーの対象として適していました。

最後に

PagerDuty Event Orchestrationでメールアラートが意図せず1つのインシデントにまとめられてしまう事象について、原因と対処法をまとめました。

Email Integration単体であればEmail Management RulesのUIで完結する重複排除の調整も、Event Orchestrationを経由する構成ではOrchestration側のdedup_keyで制御する必要があります。

メール経由のアラートで意図しない重複排除に困っている方の参考になれば幸いです。

以上、たかやま(@nyan_kotaroo)でした。