authoring-error-tracking-alerts

エラートラッキングアラートの作成

エラートラッキングアラートの作成は、測定ではなく ルーティング の問題です。トリガーイベントはすでに存在し、取り込みパイプラインで実際の条件に基づいて発火します。ユーザーの意図に合ったトリガーを選び、すでに設定されているものと重複しないようにして、ユーザーが実際に対応できる宛先につなぐのが役割です。

このスキルを使う場面

• ユーザーが、プロジェクトのエラーや例外に関するアラート／通知の設定を依頼した場合。
• エラートラッキングを有効にした後、最初に設定するアラートを求めている場合。
• ユーザーがイシューのリンクを貼り、「これがまた発生したら通知して」と依頼した場合。通常は、イシューごとのプロパティフィルターを使った _reopened です。

このスキルを使わない場面

• スパイク検出器自体（倍率、ウィンドウ、しきい値）の調整。これはスパイク検出設定エンドポイントで行うもので、現在 MCP からは利用できません。
• 進行中のインシデントの調査。アラートを追加作成するのではなく、posthog:query-error-tracking-issue と posthog:query-error-tracking-issue-events を使って、イシューやそのイベントを直接クエリしてください。
• ボリュームしきい値アラート（一定期間内の $exception イベント数）の設定。これはログ形式のアラートであり、ここでは対象外です。エラートラッキングアラートは、代わりにライフサイクルイベントを利用します。

ツール

ツール	役割	用途
posthog:error-tracking-alerts-list	既存のアラートを一覧表示します（ページネーション対応）。作成前に重複を確認します。	ステップ 2 — 重複確認。
posthog:integrations-list	ユーザーの Slack ワークスペース ID を検索します（kind=slack で絞り込み）。	ステップ 3 — チャンネル選択。
posthog:integrations-channels-retrieve	ワークスペース内の Slack チャンネルを一覧表示します。	ステップ 3 — チャンネル選択。
posthog:error-tracking-alerts-create	アラートを作成します（type=internal_destination の HogFunction）。	ステップ 4 — 送信。
posthog:error-tracking-alerts-partial-update	既存のアラートの有効／無効を切り替えたり、名前を変更したり、変更を加えたりします。	調整する場合。作成時は使用しません。
posthog:error-tracking-alerts-delete	アラートをソフト削除します。	ユーザーから「削除して」と言われた場合。

トリガーイベント — アラートごとに必ず1つ選択してください

ライフサイクルイベントは3種類あります。それぞれ「ノイズと緊急性」のバランスが異なります。ここでアラート疲れが起きる最も一般的な原因は、間違ったイベントを選ぶことです。

イベント	発生条件	使用する場合
$error_tracking_issue_created	新しい課題が初めて発生したとき。	小規模なプロジェクト、または新しい種類のエラーをすべて確認する価値があるプロジェクト向けです。大規模でノイズの多いプロジェクトでは通知が殺到します。
$error_tracking_issue_reopened	以前に解決した課題で、再びイベントが発生したとき。	すでにトリアージした課題のリグレッションを検知する場合に使用します。「再発したら知らせてほしい」という用途に最も安全なトリガーです。
$error_tracking_issue_spiking	スパイク検出器が課題の異常な発生量を検知したとき。	ベースラインの発生量が多い本番環境のプロジェクト向けです。しきい値と倍率はプロジェクト全体で共有されるため、使用前にスパイク設定を確認してください。

ユーザーの指示が曖昧な場合（「エラーを知らせて」など）は、デフォルトで_spikingを選択してください。これは最も多くのシグナルを捉え、アラート疲れを引き起こす可能性が最も低いトリガーです。先に進む前に、必ず明示的に確認してください。

ワークフロー

1. 意図を確認する

作成を始める前に、ユーザーから次の3点を確認してください。

• トリガーイベント。 指定されていない場合は_spikingを推奨し、確認を求めてください。黙って選択してはいけません。
• チャンネル。 Slack のチャンネル名、Webhook URL、Linear のチームなどです。本番用チャンネルをハードコードしてはいけません。ユーザーが「開発チャンネル」と言った場合は、正確なチャンネル ID または名前を確認してください。
• 対象範囲。 すべての課題（最も一般的）、または特定の課題／例外の種類／担当者に限定するかを確認してください。

2. 既存のアラートと重複しないか確認する

判断する前に、すべての送信先を確認します。このエンドポイントはページネーションに対応しており、デフォルトでは1ページあたり100行を返すため、送信先が数百件あるプロジェクトでデフォルトのまま1回呼び出すと、古いアラートを見落とします。

posthog:error-tracking-alerts-list を type: ["internal_destination"] と limit: 1000 を指定して呼び出します。レスポンスの next が null でない場合は、next が null になるまで offset を指定してページを取得し続けます。その後、収集した行をクライアント側で filters.events[].id と filters.properties 内の issue ごとのスコープで絞り込みます。

一覧のレスポンスには inputs が含まれないため、各行の通知先となるチャンネルや URL はわかりません。代わりに name と description から送信先を読み取ります。以下の命名規則では、チャンネルが名前に含まれています。イベントとスコープは一致するものの、名前から通知先がわからない場合は、推測せず、一致した名前をユーザーに提示して、その中に意図したアラートがあるか尋ねてください。

• 同じイベントを同じチャンネルに同じスコープで通知するアラートが存在する場合は、そこで停止します。すでに存在するとユーザーに伝え、変更するか（その場合は error-tracking-alerts-partial-update を使用します）、スキップするかを尋ねてください。
• 同じイベントのアラートが同じチャンネルに複数あると、Slack メッセージが重複して届きます。ユーザーがこれを望むことはほとんどありません。
• 同じイベントのアラートを異なるチャンネルに送信する場合（例：一方は #oncall、もう一方は oncall webhook）は問題ありません。意図的な場合もあるため、確認してください。
• 同じイベント、同じチャンネルでも、異なるスコープのアラート（例：それぞれ別の $exception_issue_id に固定された2つの _reopened アラート）は重複ではありません。追加する前に確認してください。スコープを指定したアラートと、すべての issue を対象とするアラートを同じチャンネルに送ると、どちらもスコープ対象の issue について発火することに注意してください。

PostHog の「アラートが設定済み」という推奨表示は filters.events のみを確認します。issue ごとの filters.properties を追加しても、アラートバナーに表示されるステータスには影響しません。

3. インテグレーションを選択する

Slack の場合：

1. posthog:integrations-list を kind=slack で呼び出し、インテグレーションの id（整数）を選択します。
2. その ID を指定して posthog:integrations-channels-retrieve を呼び出し、チャンネル ID（例：C0123ABC）を選択します。"#oncall" のようなチャンネル名も使用できますが、チャンネル ID を推奨します。ID は名前を変更しても変わりません。

Webhook の場合：ユーザーから https:// URL を1つ指定してもらいます。http:// URL は受け付けません。

Linear / GitHub / GitLab の場合：まず posthog:integrations-list でインテグレーションが接続されていることを確認し、issue を登録するプロジェクト / リポジトリ / チームをユーザーに尋ねます。

4. アラートを作成する

以下を指定して posthog:error-tracking-alerts-create を呼び出します。

{
  "type": "internal_destination",
  "template_id": "template-slack",
  "name": "<short, channel-attributed name>",
  "enabled": true,
  "filters": {
    "events": [{ "id": "$error_tracking_issue_created", "type": "events" }]
  },
  "inputs": {
    "slack_workspace": { "value": <slack_integration_id_int> },
    "channel": { "value": "<channel_id>" },
    "text": { "value": "..." },
    "blocks": { "value": [...] }
  }
}

各イベントに対応する標準の Slack blocks ペイロードは、references/block-templates.md にあります。一致するブロックをそのままコピーしてください。これは製品内のアラートウィザードと一致するため、エージェントが作成したアラートも UI で作成したものと同じ表示になります。

issue ごとのスコープを指定するには、created / reopened の場合に限り（spiking イベントには exception プロパティがありません）、filters に以下を追加します。

"properties": [
  { "key": "$exception_issue_id", "value": "<issue_uuid>", "operator": "exact", "type": "event" }
]

そのほかに使用できるプロパティフィルター：$exception_types（例外クラス名の配列）、name（issue のタイトル）。各イベントで使用できるすべてのプロパティについては、references/event-triggers.md を参照してください。

5. 確認する

アラートの名前、トリガーイベント（人が読みやすい表現）、送信先、メッセージ本文の1行プレビューをユーザーに伝えます。Slack ワークスペース ID や webhook URL は機密情報のため、伝えないでください。無効化する方法として、「error-tracking-alerts-partial-update で enabled: false を設定するか、送信先 UI で切り替えると、このアラートを一時停止できます」と伝えてください。

命名規則

<トリガー> · <チャンネル> (auto) の形式を使うと、ユーザーがアラート一覧を確認して、エージェントが作成した項目を見分けやすくなります。 例：

• Issue spiking · #oncall (auto)
• Issue reopened · #regressions-webhook (auto)
• Issue created · Linear/Eng (auto)

アラートには課題のタイトルを使わないでください。アラートは多くの課題に一致する可能性があり、課題が進展するとタイトルが古くなるためです。

トークン節約のルール

• 候補ごとではなく、最初に posthog:error-tracking-alerts-list を一度だけ完全にスキャンします。next が null になったときにのみスキャン完了です。一度ページをすべて取得し、収集した行をすべての候補で再利用します。
• 同じワークスペースに送信する複数のアラートでは、インテグレーションの検索を一度だけ行って再利用します。
• 各アラートを作成する前に、チャンネル／URLをユーザーに確認します。ユーザーが明示していない宛先へのアラートをまとめて作成してはいけません。
• アラートごとの反復は最大1ラウンドに制限します。ユーザーが3つのアラートを希望した場合、作成呼び出しは3回です。アラートごとに3回ではありません。

出力

以下の形式で実施内容を報告します。

• 作成した各アラート：名前、トリガーイベント、宛先（チャンネル名またはWebhookホスト。完全なURLは含めない）、有効状態。
• スキップした各アラート：トリガー＋チャンネル＋理由（既存、ユーザーが辞退、インテグレーションが見つからない）。
• ユーザーが次に行うべきこと：スパイク検出設定を有効にする（_spiking を選択し、検出器が有効になっていない場合）、ソースマップを設定する（アラートのスタックトレースリンクを解決できるようにする）、または1日様子を見てからアラートフィルターを調整する。

関連スキル

• triaging-error-issues — アラートを設定する前に、実際に重要な課題を見極めます
• investigating-error-issue — アラートが発火した課題を詳しく調査します
• authoring-log-alerts — 例外ではなくログ行を対象に、同じアラート設定を行います