grouping-noisy-errors

ノイズの多いエラーをグループ化する

スタックフレームやメッセージに変動するデータ（ランダムな ID、動的なファイルパス、ビルドハッシュ、匿名関数名）が含まれていると、同じエラーが別々の issue として何十件も報告されることがあります。解決するには、2 つの手順が必要です。まず、既存の issue を 1 つの対象に統合し、次に、同じ呼び出し元からの今後のイベントに単一の正規フィンガープリントを割り当て、新しい issue が次々と作成されないようにするグルーピングルールを作成します。

まず重要な点として、ここでいう「同じエラー」の範囲は狭いものです。名前やメッセージの一文が同じでも、異なるコードパス、異なる SDK、異なるランタイムに由来する 2 つの issue は別のエラーであり、ユーザーが「同じ種類のバグ」と捉えていたとしても、分けておく必要があります。両方のメッセージに「undefined」が含まれているからといって、フロントエンドの TypeError とバックエンドの TypeError をまとめてしまうと、それぞれの問題をチームが見つけるための手がかりが失われます。ステップ 1 の基準は、これを防ぐためにあります。

利用可能なツール

ツール	目的
posthog:query-error-tracking-issues-list	重複候補の issue を検索する
posthog:query-error-tracking-issue	個々の issue の簡潔な詳細を取得する
posthog:query-error-tracking-issue-events	スタックとメッセージを含む、サンプリングされた $exception イベント
posthog:error-tracking-issues-merge-create	既存の issue を対象に統合する
posthog:error-tracking-issues-split-create	統合に誤りがあった場合、フィンガープリントを個別に切り分ける
posthog:error-tracking-grouping-rules-create	今後のイベントを自動的に 1 つの issue にグループ化する
posthog:error-tracking-grouping-rules-list	新しいルールを追加する前に、既存のグルーピングルールを確認する
posthog:error-tracking-issues-partial-update	統合後に対象の名前を変更するか、説明を更新する

統合とグルーピングルールの違い

この 2 つのツールは、問題の異なる側面を解決します。

• 統合は一度限りの処理です。既存の issue を対象にまとめ、そのイベントを再度関連付けます。今後のイベントは引き続き元のフィンガープリントでグループ化されます。ノイズの多い同じパターンによって新しいフィンガープリントが作られ続ける場合、統合を繰り返すだけのいたちごっこになります。
• グルーピングルールは継続的に適用されます。一致するイベントのフィンガープリントを取り込み時に custom-rule:<rule_id> へ書き換えるため、今後一致するイベントは新しいフィンガープリントを次々と作成するのではなく、すべて同じ正規フィンガープリントを共有します。最初に一致したイベントでは、そのフィンガープリントをキーとして新しい issue が作成されるか、すでにそのフィンガープリントに紐付いている issue に振り分けられます。

issue が繰り返し発生する場合は、両方を組み合わせて使います。過去の重複 issue を対象の issue に統合してから、ルールを作成します。ルール API は対象の issue ID を受け付けません。ルールの適用が始まったら、結果として作成された custom-rule:... の issue を同じ対象に統合すると、統合状態が維持されます。再発が見込まれない過去の大量発生には、統合だけを使います。既存の issue との統合が不要で、先回りして対処したい新しいパターンには、グルーピングルールだけを使います。

ワークフロー

ステップ 1 — 重複を確認する

例外の種類またはメッセージで検索し、候補を見つけます。

posthog:query-error-tracking-issues-list
{
  "searchQuery": "TypeError: Cannot read property",
  "status": "active",
  "limit": 50,
  "orderBy": "occurrences",
  "dateRange": { "date_from": "-30d" }
}

候補ごとに、サンプリングされた例外イベントを 1 件取得して、スタック、種類、メッセージを比較します。

posthog:query-error-tracking-issue-events
{
  "issueId": "<candidate_issue_id>",
  "limit": 1,
  "include": ["exception", "stacktrace", "environment"]
}

この操作は候補ごとに 1 回実行します。ツールのデフォルトは onlyAppFrames: true で、アプリ内の最上位フレームがひと目でわかるようになります。候補同士で最上位フレームと例外の種類が同じであれば、同じエラーである可能性が高いですが、統合する前に、必ず以下のチェックリスト全体に照らして確認してください。

同じエラーですか？

次の項目がすべて一致する場合に限り、2つの問題を重複として扱います。

• $lib が同じ SDK であること。ブラウザー／JS SDK では $lib は web（posthog-js ではありません）として記録されます。サーバー SDK では posthog-python、posthog-node などが使われます。思い込みで判断せず、read-data-schema（$exception の $lib に対する event_property_values）で正確な値を確認してください。値を間違えると、何も一致しないままになります。例外の種類が一致していても、異なる SDK から発生したエラーは、ほとんどの場合、別のコードパスに由来します。
• 例外の種類（$exception_types）が同一であること。
• アプリ内スタックフレームの最上部が、同じファイルと同じ関数を指していること。行番号や関数内のわずかなオフセットの違いは問題ありません。最上部のファイルまたは関数が異なる場合は、別のバグです。
• メッセージのテンプレートが同じで、違いが ID、ハッシュ、タイムスタンプ、動的なパスなどの変動データに限られること。動詞、対象、操作が異なる場合は、別のバグです。
• $exception_handled が一致すること（どちらも処理済み、またはどちらも未処理）。捕捉されたケースと捕捉されなかったケースは、異なるコードパスであり、分けておくと有益です。

どれか1つでも異なる場合は、重複ではありません。個別に調査してください（investigating-error-issue）。

まとめてはいけないもの

以下は、デバッグに役立つ情報を損なう失敗パターンです。ユーザーが「同じ種類のバグ」と説明していても、これらをまたいでまとめないでください。

• 同じ例外の種類でも、フロントエンドとバックエンドで発生したもの。 ブラウザーのバンドルで発生した TypeError と Node サービスで発生した TypeError は、名前が同じで、メッセージに同じ単語が含まれることもよくありますが、スタック、ランタイム、修正方法はすべて異なります。
• SDK／プラットフォームが異なるもの。 web（ブラウザー／JS）、posthog-python、posthog-node は、それぞれ異なる呼び出し元です。
• 種類は同じでも、スタック最上部のファイルまたは関数が異なるもの。 OrderService.cancel からスローされた NullPointerException は、メッセージにどちらも「user was null」と書かれていても、PaymentService.refund からスローされたものと同じバグではありません。
• 捕捉されたものと捕捉されなかったもの。 $exception_handled だけが異なる2つの問題は、通常、一方ではコードがエラーを握りつぶし、もう一方では伝播させるという違いがあります。別々に保つことで、その違いが明確になります。
• 同じ表現を含む、概念的に似ているだけのバグ。 「Cannot read property of undefined」は、互いに独立した多くのバグで発生します。スタックフレームが一致しない限り、メッセージの類似性だけでは不十分です。

ステップ 2 — 対象の問題を選ぶ

他の問題を統合する対象を選びます。

• 発生回数が最も多いもの — ダッシュボードの連続性を保つため、最も代表的な問題を残します。
• 名前と説明が最も適切なもの — ユーザーが注釈を付けている場合は、それを優先します。
• first_seen が最も古いもの — 元の時系列を保ちます。

対象の ID を控えてください。他の候補は、統合する ids になります。

ステップ 3 — 既存の重複を統合する

posthog:error-tracking-issues-merge-create
{
  "id": "<target_issue_id>",
  "ids": ["<duplicate_id_1>", "<duplicate_id_2>", "..."]
}

統合は破壊的な操作（注釈 destructive: true）です。問題を対象に統合すると、元の問題はアクティブなリストから削除されます。実行前に、対象をユーザーに確認してください。失敗の範囲を限定するため、統合 1 回あたりの元 ID は約 50 件までにしてください。対象がさらに多い場合は、分割して実行します。

統合後、変更が問題リストにすぐ反映されないことがあります。呼び出し直後に再度リストを取得しても、短時間は元の問題が表示される場合があります。後続の error-tracking-issues-list 呼び出しで変化が見られない場合は、統合を再実行せず、数秒待ってから再度問い合わせてください。

統合後に対象のメタデータが適切でない場合（重複側の名前のほうが適切だった場合など）は、再統合するのではなく、error-tracking-issues-partial-update を使って対象の名前または説明を修正してください。

ステップ 4 — グルーピングルールが必要か判断する

次の両方に当てはまる場合は、グルーピングルールを作成する価値があります。

• 同じパターンから新しいフィンガープリントが引き続き生成されている（前回の統合後に新たな重複が発生している）
• 関連のないエラーを誤って取り込まないプロパティフィルターで、そのパターンを表現できる

標準の例外プロパティ（メッセージには$exception_types、$exception_values、ファイルパスには$exception_sources、関数名には$exception_functions）は、キャプチャ時には配列です。PostHogのプロパティフィルターではこれらを特別に扱うため、各フィルターは配列の個々の要素に対して照合され、標準演算子（exact、is_not、icontains、not_icontains、regex、not_regex）はすべて値をそのまま指定して機能します。たとえば、exact "TypeError"のように指定し、exact '["TypeError"]'やregex '"TypeError"'とは指定しません。

単数形の$exception_type、$exception_messageと$exception_stack_trace_rawは、イベントの1％未満にしか出力されません。これらに基づいてフィルターを作成すると、ルールが一度も一致しないままになってしまいます。

メッセージに変動部分がある場合（例：TypeError at /static/main.<hash>.js）、$exception_valuesの正規表現フィルターが機能します。既知のファイル内の行番号に変動部分がある場合は、$exception_sourcesに対するicontainsが機能します。$exception_handledも絞り込みに便利な条件です。処理済みと未処理を混在させず、分けてください。

次の場合はグルーピングルールを作成しないでください。

• 重複が過去に発生したものである（一度限りのバックフィルで、新たな発生はない）場合 — 統合だけで十分です
• 安全性を確保できるほど絞り込んだフィルターを書けない場合 — 代わりに統合の頻度を上げ、後で再検討してください

ステップ 5 — グルーピングルールを作成する

ステップ1の「同じエラー」チェックリストをルールフィルターに反映します。チェックリストより緩い条件に一致するルールは、関連のないバグをそのまま延々と統合してしまいます。ルールは今後のすべてのイベントに適用されるため、統合より危険です。最低限、SDKと例外タイプで範囲を絞り、さらに3つ目の条件（$exception_sourcesによるファイルパス、または$exception_valuesによる特定のメッセージフレーズ）を追加して、呼び出し箇所を特定してください。

まず$libの値を確認してください。ブラウザー／JS SDKがキャプチャする値はposthog-jsではなく$lib="web"です。そのため、posthog-jsでフィルターするルールは一度も一致しません。ルールに値を設定する前に、read-data-schema（$exceptionに対する$libのevent_property_values）で確認してください。

posthog:error-tracking-grouping-rules-create
{
  "filters": {
    "type": "AND",
    "values": [
      {
        "type": "event",
        "key": "$lib",
        "operator": "exact",
        "value": "web"
      },
      {
        "type": "event",
        "key": "$exception_types",
        "operator": "exact",
        "value": "TypeError"
      },
      {
        "type": "event",
        "key": "$exception_sources",
        "operator": "icontains",
        "value": "/static/checkout/"
      },
      {
        "type": "event",
        "key": "$exception_values",
        "operator": "icontains",
        "value": "Cannot read property"
      }
    ]
  },
  "description": "Cleanup: collapse noisy checkout TypeError fingerprints (web)"
}

ルールは順番に評価されます。まず既存のルールを一覧表示してください（posthog:error-tracking-grouping-rules-list）。すでにパターンの一部をカバーするルールがある場合は、よく似たルールを追加するより、そのルールのフィルターを調整してください。

省略可能なassigneeフィールドを指定すると、そのルールで作成された課題が自動的に割り当てられます。ユーザーがルールに所有者を設定することを明示的に希望しない限り、省略してください。

ステップ 6 — 確認して統合する

統合が成功したことを確認するため、統合先の課題の最近のイベントをサンプル確認します。ルールのcustom-rule:<rule_id>フィンガープリントにイベントが一致し始めるかを確認してください。最初の一致によって、新しい課題が作成されるか、そのフィンガープリントにすでに紐づいている課題に振り分けられます。イベントを新しいカスタムルールの課題に散在させず、過去の統合先にまとめておくには、2回目の統合を実行し、カスタムルールの課題を統合先にまとめます。

ルール以外の新しいフィンガープリントがルール作成後も引き続き発生する場合は、フィルターが狭すぎます。範囲を広げてください。

ヒント

• ユーザーは、グループ化ルールと割り当てルールを混同することがよくあります。グループ化ルールは、イベントが_どの_課題に分類されるかを決めます。割り当てルールは、結果として作成された課題を_誰が_担当するかを決めます。
• イベントを調べずに、「似ている」という理由だけで課題を統合しないでください。異なるファイルで発生した2つのTypeErrorは、別々のバグです。
• スタックフレームが標準的なグループ化シグナルです。取り込み時にすでにスタックに基づいてフィンガープリントが作成されるため、安定したスタックは自動的にグループ化されます。自然なフィンガープリントではイベントがばらけてしまう場合（変動するファイル名、ハッシュ化された関数名、動的な行番号など）に、グループ化ルールを使って動作を上書きします。
• グループ化ルールを無効化したり、条件を厳しくしたりしても、既存のイベントのグループ化は遡って解除されません。今後のイベントは正しく振り分けられますが、過去のイベントはそのままです。統合された課題からフィンガープリントを個別に分離する必要がある場合は、error-tracking-issues-split-createを使用してください。
• グループ化ルールは、UI の「Project settings → Error tracking → Grouping rules」にあります。ルールの場所を尋ねられたら、この項目を案内してください。

関連スキル

• suppressing-noisy-errors — 価値のないイベントを再グループ化するのではなく、完全に破棄します
• triaging-error-issues — グループ化を整理した後で、課題キューの優先順位を付け直します
• investigating-error-issue — 統合された課題を最初から最後まで調査します