omnibus-instrument-error-tracking

PostHog のエラートラッキングを追加する

このスキルを使うと、アプリケーションの例外を捕捉して監視する PostHog のエラートラッキングを追加できます。機能の実装後や PR のレビュー後に使用して、完全なスタックトレースとソースマップでエラーが追跡されるようにします。PostHog がまだインストールされていない場合は、このスキルで SDK の初期設定も行えます。あらゆるプラットフォームや言語に対応しています。

対応プラットフォーム：React、Next.js、Web（JavaScript）、Node.js、Python、Ruby、Ruby on Rails、Go、Angular、Svelte、Nuxt、React Native、Flutter、Android、Hono。

手順

以下の手順を順番どおりに実行してください。

STEP 1：コードベースを分析して、プラットフォームを特定します。

• 依存関係ファイル（package.json、requirements.txt、go.mod、Gemfile、composer.json など）を確認し、言語とフレームワークを特定します。
• ロックファイル（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb）を確認し、パッケージマネージャーを特定します。
• PostHog の設定（SDK の初期化、環境変数など）がすでにあるか確認します。PostHog がすでにインストールされ、初期化されている場合は、STEP 4 に進みます。

STEP 2：計測方法を調べます。（PostHog がすでに設定されている場合はスキップします。） 2.1. 検出したプラットフォームに一致する以下のリファレンスファイルを探します。このファイルは、SDK の初期化、例外の自動捕捉、フレームワーク固有のエラートラッキングパターンに関する信頼できる情報源です。今すぐ読みます。 2.2. 一致するリファレンスがない場合は、一般知識とウェブ検索を利用します。主な検索先として posthog.com/docs を使用します。

STEP 3：PostHog SDK をインストールして初期化します。（PostHog がすでに設定されている場合はスキップします。）

• 検出したプラットフォーム用の PostHog SDK パッケージを追加します。package.json を手動で編集せず、パッケージマネージャーのインストールコマンドを使用します。
• パッケージのインストールは必ずバックグラウンドタスクとして実行します。完了を待たず、インストールを開始したらすぐに他の作業を進めます。
• フレームワークのリファレンスに従って、初期化する場所と方法を決めます。

STEP 4：例外の自動捕捉を有効にします。

• プラットフォームのリファレンスに従って、例外の自動捕捉を有効にします。これにより、追加のコードなしで未処理の例外が自動的に捕捉されます。

STEP 5：手動のエラー捕捉を追加します。

• エラー境界、catch ブロック、エラーを明示的に捕捉すべき重要なユーザーフローを特定します。
• これらの箇所に posthog.captureException() またはプラットフォームに対応する同等の処理を追加します。
• 既存のエラー処理の基本的なアーキテクチャは変更しないでください。追加は最小限かつ対象を絞って行います。
• ファイルを書き込む直前に、必ずそのファイルを読み込んでください。

STEP 6：ソースマップをアップロードします（フロントエンド／モバイルのみ）。

• スタックトレースが縮小済みバンドルではなく元のソースコードに対応するよう、ソースマップのアップロードを設定します。
• アップロード設定（ビルドプラグイン、CI スクリプトなど）は、プラットフォーム固有のリファレンスに従います。

STEP 7：環境変数を設定します。

• env-file-tools MCP サーバーが接続されている場合は、check_env_keys を使って既存のキーを確認し、次に set_env_values を使って PostHog の API キーとホストを作成または更新します。
• これらの環境変数をコード内で参照し、値をハードコードしないでください。

STEP 8：検証してクリーンアップします。

• プロジェクトにエラーがないか確認します。package.json に型チェックやビルドのスクリプトがないか調べます。
• 作成したコンポーネントが実際に使われていることを確認します。
• package.json にあるリンターや Prettier に類するスクリプトを実行します。

参考ファイル

• references/react.md - React のエラートラッキングのインストール - ドキュメント
• references/web.md - Web のエラートラッキングのインストール - ドキュメント
• references/nextjs.md - Next.js のエラートラッキングのインストール - ドキュメント
• references/node.md - Node.js のエラートラッキングのインストール - ドキュメント
• references/python.md - Python のエラートラッキングのインストール - ドキュメント
• references/ruby.md - Ruby のエラートラッキングのインストール - ドキュメント
• references/ruby-on-rails.md - Ruby on rails のエラートラッキングのインストール - ドキュメント
• references/go.md - Go のエラートラッキングのインストール - ドキュメント
• references/angular.md - Angular のエラートラッキングのインストール - ドキュメント
• references/svelte.md - Sveltekit のエラートラッキングのインストール - ドキュメント
• references/nuxt.md - Nuxt のエラートラッキングのインストール（v3.7 以降） - ドキュメント
• references/react-native.md - React native のエラートラッキングのインストール - ドキュメント
• references/flutter.md - Flutter のエラートラッキングのインストール - ドキュメント
• references/android.md - Android のエラートラッキングのインストール - ドキュメント
• references/hono.md - Hono のエラートラッキングのインストール - ドキュメント
• references/fingerprints.md - フィンガープリント - ドキュメント
• references/alerts.md - エラートラッキングのアラートを送信 - ドキュメント
• references/monitoring.md - 問題を監視および検索 - ドキュメント
• references/assigning-issues.md - チームメイトに問題を割り当てる - ドキュメント
• references/upload-source-maps.md - ソースマップをアップロード - ドキュメント

各プラットフォームのリファレンスには、SDK 固有のインストール方法と手動キャプチャのパターンが記載されています。ユーザーのスタックに合ったものを参照してください。

重要な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。ハードコードしないでください。
• 最小限の変更：既存のエラー処理にエラートラッキングを追加してください。既存のコードを置き換えたり、構成し直したりしないでください。
• まず自動キャプチャ：手動キャプチャを追加する前に、例外の自動キャプチャを有効にしてください。
• ソースマップ：スタックトレースが縮小されたバンドルではなく、元のソースコードを示すように、ソースマップをアップロードしてください。
• 境界では手動キャプチャ：グローバルハンドラーに伝播しないエラーについては、エラー境界や catch ブロックで captureException() を使用してください。