triaging-error-issues

エラー追跡の課題をトリアージする

ユーザーが「何が壊れていますか？」と尋ねたり、毎日のエラーレビューを希望したりする場合、目標は人が確認する価値のある課題を優先順位順にまとめた短いリストを提示することです。有効な課題をすべて羅列するのではありません。ほとんどのプロジェクトには数百件の有効な課題がありますが、重要なものは通常、新しい（過去24〜48時間以内に初めて検出された）、急増している、または多くの異なるユーザーに影響している課題です。

利用可能なツール

ツール	目的
posthog:query-error-tracking-issues-list	集計指標（発生回数、ユーザー数、セッション数）を含む課題を一覧表示し、順位付けします
posthog:query-error-tracking-issue	単一の課題の詳細を簡潔に表示します（ステータス、担当者、トップフレーム、リリース）
posthog:query-error-tracking-issue-events	スタック、URL、ブラウザー、$session_id を含むサンプリング済みの $exception イベント
posthog:query-session-recordings-list	課題に遭遇したユーザーのリプレイを検索します
posthog:inbox-reports-list	プロジェクトで Inbox を使用している場合、事前に選別された対応可能なシグナルを表示します

ワークフロー

ステップ 1 — 期間とシグナルを選ぶ

ユーザーの表現から期間を読み取ります。指定がない場合のデフォルトは次のとおりです。

• 「今日」／「今朝」／「今すぐ」 → dateRange: { date_from: "-24h" }
• 「今週」／「月曜日以降」 → -7d
• オンコールのシフト引き継ぎ → -24h

「重要」の意味を決めます。

• 新しい課題 — orderBy: "first_seen"、orderDirection: "DESC"、短い期間。 最近のデプロイで発生したリグレッションを検出します。
• 影響が大きい課題 — orderBy: "users" は影響を受けたユーザーの実数で順位付けします。深刻度の判断には、生の発生回数より適しています（ボットのループは発生回数を増やしますが、ユーザー数は1人です）。
• 増加傾向 — 短い期間と長いベースライン期間で orderBy: "occurrences" を使い、急増を見つけます。

ステップ 2 — 候補リストを取得する

まず範囲を絞って検索し、返される課題が少なすぎる場合は広げます。

posthog:query-error-tracking-issues-list
{
  "status": "active",
  "orderBy": "users",
  "orderDirection": "DESC",
  "dateRange": { "date_from": "-24h" },
  "limit": 20,
  "volumeResolution": 24
}

各行のスパークラインで、急増と安定した横ばいを見分けるのに十分な解像度が得られるよう、期間に合わせて volumeResolution を設定します（-24h なら24個、-14d なら14個など）。 バケットが1つだけでは合計しか分からず、推移の形は分かりません。

新しい課題のみを対象にする場合は、orderBy: "first_seen" を指定したクエリも並行して実行します。

{
  "status": "active",
  "orderBy": "first_seen",
  "orderDirection": "DESC",
  "dateRange": { "date_from": "-24h" },
  "limit": 10
}

ブラウザー向け SDK とサーバー向け SDK が混在するプロジェクトでは、ユーザー数上位のリストは通常、サーバー側のエラーで埋め尽くされます（呼び出しごとに新しい distinct_id が割り当てられることが多いためです）。 library フィルターで範囲を絞ります。値は npm パッケージ名ではなく、SDK の $lib に一致します。例：

• web — posthog-js（ブラウザー）
• posthog-node、posthog-python、posthog-ruby、posthog-go、posthog-php、posthog-java、posthog-elixir — サーバー向け SDK
• posthog-edge — Cloudflare Workers／エッジランタイム
• posthog-ios、posthog-android、posthog-react-native、posthog-flutter — モバイル

ステップ 3 — ノイズを取り除く

リストには既知のノイズも含まれます。提示する前に、次の課題を除外するか、注意点として伝えます。

• 期間中の発生量が横ばいの課題 — 新しいものではなく、ユーザーはすでにその状態を受け入れています。ユーザー数上位に入っている場合のみ取り上げます。
• ボットのみが発生させている課題 — すべてのイベントがヘッドレスブラウザーまたはクローラーのユーザーエージェントから発生している場合、トリアージするのではなく、抑制（suppressing-noisy-errors）の対象として示します。

課題が新しいものか再発しているものか判断できない場合は、first_seen を期間の開始時刻と比較します。

• first_seen が期間内 → 新しく、注意が必要です
• first_seen は数週間前だが、現在急増している → 注意が必要なリグレッションです
• first_seen は数週間前で、発生量が横ばい → バックグラウンドノイズです

ステップ 4 — 上位の項目にコンテキストを追加する

上位 3〜5 件の候補について、サンプルの例外を取得し、概要にタイトルだけでなくスタックフレームと URL も含めます。生の SQL ではなく posthog:query-error-tracking-issue-events を使用してください。正規化されたフィールド（$exception_types、$exception_values、$current_url、ブラウザー／OS、$session_id）が返され、スタックからベンダー由来のノイズを取り除くため、デフォルトで onlyAppFrames: true が設定されています。

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

ユーザーがユーザーの操作内容を確認したい場合は、最適な関連録画を選ぶために finding-replay-for-issue に引き継ぎます。トリアージ対象のすべての問題についてリプレイを取得するのではなく、ユーザーが詳しく調べたいと指定したものだけを取得してください。

ステップ 5 — トリアージリストを提示する

最初に、概要を 1 行で示します（「過去 24 時間に新しい問題が 3 件、急増が 1 件、影響の大きい問題が 5 件」など）。続いて、選択したシグナル順に並べた短い表を提示します。

問題	初回検出	ユーザー数	セッション数	サンプルメッセージ	推奨アクション
...	2h ago	142	198	TypeError ... at checkout.js:42	調査する
...	急増	67	89	Network request failed	監視する — 一時的な可能性あり
...	3d ago	12	12	chrome-extension:// timeout	抑制する（拡張機能のノイズ）

各項目には、調査する（investigating-error-issue）、割り当てる （error-tracking-issues-partial-update）、抑制する（suppressing-noisy-errors）、 統合する（grouping-noisy-errors）、またはすでに修正済みと判明している場合は解決するのいずれかを提案します。

ヒント

• 1 回のデプロイで、関連する新しい問題が複数表面化することがよくあります。複数の新しい問題で properties.$lib_version（または、SDK で値が設定されるよう構成されている場合は properties.$exception_releases）が共通しているときは、まとめて提示します。ロールバックの判断は、個々の問題ではなくクラスターに基づいて行います。
• ユーザー向けアプリでは、「ユーザー数」が適切な深刻度の指標です。個別の distinct_id の概念がないバックエンドサービスでは、代わりに sessions または occurrences を使用してください。
• トリアージの一環として、自動的に割り当てたり解決したりしないでください。リストを提示し、判断はユーザーに任せます。一括操作には専用のスキルを使用してください。
• プロジェクトで Inbox（posthog:inbox-reports-list）を使用している場合は、最初に確認してください。PostHog がすでに実行価値の高い問題を選別している可能性があり、再度抽出する手間を省けます。
• 各行の _posthogUrl（各問題の行に返されます）を提示し、ユーザーが詳しく調べたい場合に問題ページへ直接移動できるようにしてください。リンクを自分で作成する場合は、必ず完全な /project/<project_id>/error-tracking/<id> パスを使用し、/error-tracking/<id> だけのパスは使用しないでください。

関連スキル

• investigating-error-issue — トリアージリストから単一の問題を詳しく調査します
• grouping-noisy-errors — 重複した問題や細分化されすぎた問題によってトリアージが埋もれている場合に使用します
• suppressing-noisy-errors — 既知のノイズに該当するフィンガープリントをミュートし、今後のトリアージを整理しやすくします
• authoring-error-tracking-alerts — 手作業で再トリアージする代わりに、対応が必要な問題を Slack または Webhook に送ります