instrument-logs

PostHog のログキャプチャを追加する

新規または変更したコードに PostHog のログキャプチャを追加するには、このスキルを使用します。機能の実装後や PR のレビュー後に使用して、意味のあるログイベントが構造化されたプロパティとともに記録されるようにします。PostHog のログエクスポートがまだ設定されていない場合、このスキルでは初期の OTLP エクスポーターの設定も扱います。あらゆるプラットフォームや言語に対応しています。

対応プラットフォーム：Next.js、Node.js、Python、Go、Java、Datadog、Android、React Native、iOS、および OpenTelemetry を介したあらゆる言語。

手順

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

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

• 言語、フレームワーク、既存のロギング設定を特定します。
• 依存関係ファイルとプロジェクトファイル（package.json、Podfile、Package.swift、requirements.txt、go.mod、pom.xml など）を探します。
• ログライブラリ（winston、pino、logging モジュール、logrus、log4j、serilog、os_log、Logger など）を探します。
• ロックファイル（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、Podfile.lock、Package.resolved など）を探し、パッケージマネージャーを特定します。
• PostHog のログエクスポート設定がすでにあるか確認します。OTLP エクスポーターがすでに設定されている場合は、STEP 5 に進み、新しいコードのログキャプチャを追加します。

STEP 2: ログキャプチャを調査します。（PostHog のログエクスポートがすでに設定されている場合はスキップします。） 2.1. 以下のリファレンスファイルから、特定したプラットフォームに一致するものを見つけます。これは OTLP エクスポーターの設定および既存のロギングとの統合に関する信頼できる情報源です。今すぐ読みます。 2.2. 一致するリファレンスがない場合は、代替として「その他の言語」のリファレンスを使用します。一般的な OpenTelemetry のアプローチが説明されています。

STEP 3: 依存関係をインストールします。（PostHog のログエクスポートがすでに設定されている場合はスキップします。）

• 特定したプラットフォーム用の OpenTelemetry SDK と OTLP エクスポーターパッケージをインストールします。
• 依存関係ファイルを手動で編集せず、パッケージマネージャーのインストールコマンドを使用します。

STEP 4: OTLP エクスポーターを設定します。（PostHog のログエクスポートがすでに設定されている場合はスキップします。）

• PostHog のログは OpenTelemetry プロトコルを使用します。PostHog の取り込みエンドポイントを指定して、OTLP エクスポーターを設定します。
• Android、React Native、iOS など、SDK ネイティブのログサポートがある場合は、別個の OTLP エクスポーターを追加せず、プラットフォームのリファレンスに従います。
• 正確な設定方法は、プラットフォーム固有のリファレンスに従います。

STEP 5: 既存のロギングと統合します。

• 既存のロギングと並行して PostHog ログエクスポーターを追加します。既存のログハンドラーや出力先を置き換えないでください。
• 既存ファイルの基本的なアーキテクチャは変更しないでください。追加は最小限かつ目的を絞ったものにします。
• ファイルを書き込む直前に、そのファイルを必ず読みます。

STEP 6: 構造化プロパティを追加します。

• PostHog でのフィルタリングや検索に使えるよう、ログにキーと値の構造化プロパティが含まれることを確認します。
• プレーンテキストのメッセージより、キーと値のプロパティを含む構造化ログ形式を優先します。

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

• プロジェクトに PostHog の環境変数がすでに設定されているか（.env、.env.local、フレームワーク固有の環境ファイルなどで）確認します。有効な値がすでにある場合は、この手順をスキップします。
• PostHog のプロジェクトトークンがない場合は、PostHog MCP サーバーの projects-get ツールを使って、プロジェクトの api_token を取得します。複数のプロジェクトが返された場合は、どのプロジェクトを使うかユーザーに尋ねます。MCP サーバーに接続されていない、または認証されていない場合は、PostHog のプロジェクトトークンをユーザーに尋ねます。
• PostHog のホスト URL については、projects-get MCP のレスポンスに region フィールドがあるか確認します。US は https://us.i.posthog.com、EU は https://eu.i.posthog.com に対応します。MCP のレスポンスまたは既存のプロジェクト設定からリージョンを特定できない場合は、ユーザーに「PostHog US Cloud と EU Cloud のどちらをお使いですか？」と尋ねます。US Cloud と決めつけないでください。
• OpenTelemetry エンドポイントには、上記で特定したリージョンに合わせて、US の場合は https://us.i.posthog.com/v1、EU の場合は https://eu.i.posthog.com/v1 を使用します。
• フレームワークの命名規則に従って、適切な環境ファイルにこれらの値を書き込みます。
• 値をハードコードせず、コード内でこれらの環境変数を参照します。

リファレンスファイル

• references/nextjs.md - Next.js のログのインストール
• references/nodejs.md - Node.js のログのインストール
• references/python.md - Python のログのインストール
• references/go.md - Go のログのインストール
• references/java.md - Java のログのインストール
• references/datadog.md - Datadog のログのインストール
• references/android.md - Android のログのインストール
• references/react-native.md - React native のログのインストール
• references/ios.md - Ios のログのインストール
• references/flutter.md - Flutter のログのインストール
• references/other.md - その他の言語のログのインストール
• references/start-here.md - ログの使い始め方
• references/search.md - ログの検索
• references/best-practices.md - ログ記録のベストプラクティス
• references/troubleshooting.md - ログのトラブルシューティング
• references/link-session-replay.md - セッションリプレイのリンク
• references/mcp.md - PostHog mcp 経由でログを使用する
• references/COMMANDMENTS.md - インテグレーションが従う必要のある、フレームワーク固有のルール

各プラットフォームのリファレンスには、固有の OTLP 設定、SDK のセットアップ、インテグレーションのパターンが記載されています。ユーザーの技術スタックに合ったものを選んでください。

重要な原則

• 環境変数：PostHog のキーと OpenTelemetry のエンドポイントには、必ず環境変数を使用してください。ハードコードしないでください。
• 変更は最小限に：既存のログ記録に加えてログのエクスポートを追加してください。既存のログ記録コードを置き換えたり、再構成したりしないでください。
• OpenTelemetry：PostHog のログは OpenTelemetry プロトコルを使用します。プラットフォーム SDK がネイティブのログキャプチャを提供していない場合は、PostHog の取り込みエンドポイントを指定した OTLP エクスポーターを設定してください。
• SDK ネイティブのログ：Android、React Native、iOS では、別の OTLP エクスポーターを追加するのではなく、プラットフォームのリファレンスにある SDK のロガー／キャプチャ API を使用してください。
• 構造化ログ：プレーンテキストのメッセージより、キーと値のプロパティを使用した構造化ログ形式を優先してください。