instrument-llm-analytics

PostHog AI Observability を追加する

このスキルを使用して、新規または変更されたコードで AI モデルの使用状況をトレースする PostHog AI Observability を追加します。LLM 機能を実装した後や PR をレビューした後に使用し、トークン数、レイテンシ、コストを含めて、すべての生成が記録されていることを確認してください。PostHog がまだインストールされていない場合は、このスキルで SDK の初期セットアップも行います。あらゆるプロバイダーやフレームワークに対応しています。

対応プロバイダー：OpenAI、Azure OpenAI、Anthropic、Google、Cohere、Mistral、Perplexity、DeepSeek、Groq、Together AI、Fireworks AI、xAI、Cerebras、Hugging Face、Ollama、OpenRouter。

対応フレームワーク：LangChain、LlamaIndex、CrewAI、AutoGen、DSPy、LangGraph、Pydantic AI、Vercel AI、LiteLLM、Instructor、Semantic Kernel、Mirascope、Mastra、SmolAgents、OpenAI Agents。

プロキシ／ゲートウェイ：Portkey、Helicone。

手順

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

STEP 1：コードベースを分析し、LLM スタックを特定します。

• 依存関係ファイルとインポートを調べ、LLM プロバイダーの SDK（openai、anthropic、google-generativeai など）や AI フレームワーク（langchain、llamaindex、crewai など）を探します。
• ロックファイルを調べて、パッケージマネージャーを特定します。
• 既存の PostHog またはオブザーバビリティの設定を確認します。PostHog がすでにインストールされ、LLM トレースが設定されている場合は、STEP 4 に進み、新しい LLM 呼び出しのトレースを追加します。

STEP 2：計測方法を調査します。（PostHog の LLM トレースがすでに設定されている場合は省略します。） 2.1. 検出したプロバイダーまたはフレームワークに対応する、以下のリファレンスファイルを探します。このファイルがコールバックの設定、ミドルウェアの構成、イベント取得に関する信頼できる情報源です。今すぐ読み込んでください。 2.2. 該当するリファレンスがない場合は、フォールバックとして manual-capture.md を使用します。これは、あらゆるプロバイダーで使える汎用的なイベント取得方法を説明しています。

STEP 3：PostHog SDK をインストールします。（PostHog がすでに設定されている場合は省略します。）

• PostHog SDK と、必要なコールバック／インテグレーションパッケージを追加します。
• 依存関係ファイルを手動で編集せず、パッケージマネージャーのインストールコマンドを使用します。

STEP 4：LLM トレースを追加します。

• LLM 呼び出しを計測し、すべての生成について入力トークン数、出力トークン数、モデル名、レイテンシ、コストを取得します。
• 正確なコールバック／ミドルウェアの設定には、プロバイダー固有のリファレンスに従います。
• 既存ファイルの基本的なアーキテクチャを変更しないでください。追加は最小限かつ対象を絞って行います。
• ファイルに書き込む直前に、必ずそのファイルを読み込んでください。

STEP 5：ユーザーに紐付けます。

• 可能な場合は、識別済みユーザーの distinct ID を使って LLM の生成をユーザーに関連付けます。

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

• プロジェクトに 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 と決めつけないでください。
• フレームワークの命名規則に従って、適切な環境ファイルにこれらの値を書き込みます。
• 値をハードコードせず、コード内ではこれらの環境変数を参照します。

リファレンスファイル

• references/openai.md - OpenAI のオブザーバビリティのインストール
• references/azure-openai.md - Azure OpenAI のオブザーバビリティのインストール
• references/README.md - .NET 向け PostHog.ai
• references/anthropic.md - Anthropic AI のオブザーバビリティのインストール
• references/google.md - Google AI のオブザーバビリティのインストール
• references/cohere.md - Cohere AI のオブザーバビリティのインストール
• references/mistral.md - Mistral AI のオブザーバビリティのインストール
• references/perplexity.md - Perplexity AI のオブザーバビリティのインストール
• references/deepseek.md - DeepSeek AI のオブザーバビリティのインストール
• references/groq.md - Groq AI のオブザーバビリティのインストール
• references/together-ai.md - Together AI のオブザーバビリティのインストール
• references/fireworks-ai.md - Fireworks AI のオブザーバビリティのインストール
• references/xai.md - XAI のオブザーバビリティのインストール
• references/cerebras.md - Cerebras AI のオブザーバビリティのインストール
• references/hugging-face.md - Hugging Face AI のオブザーバビリティのインストール
• references/ollama.md - Ollama AI のオブザーバビリティのインストール
• references/openrouter.md - OpenRouter AI のオブザーバビリティのインストール
• references/langchain.md - LangChain AI のオブザーバビリティのインストール
• references/llamaindex.md - LlamaIndex AI のオブザーバビリティのインストール
• references/crewai.md - CrewAI のオブザーバビリティのインストール
• references/autogen.md - AutoGen AI のオブザーバビリティのインストール
• references/dspy.md - DSPy AI のオブザーバビリティのインストール
• references/langgraph.md - LangGraph AI のオブザーバビリティのインストール
• references/pydantic-ai.md - Pydantic AI のオブザーバビリティのインストール
• references/vercel-ai.md - Vercel AI SDK のオブザーバビリティのインストール
• references/litellm.md - LiteLLM AI のオブザーバビリティのインストール
• references/instructor.md - Instructor AI のオブザーバビリティのインストール
• references/semantic-kernel.md - Semantic Kernel AI のオブザーバビリティのインストール
• references/mirascope.md - Mirascope AI のオブザーバビリティのインストール
• references/mastra.md - Mastra AI のオブザーバビリティのインストール
• references/smolagents.md - Smolagents AI のオブザーバビリティのインストール
• references/openai-agents.md - OpenAI Agents SDK のオブザーバビリティのインストール
• references/portkey.md - Portkey AI のオブザーバビリティのインストール
• references/helicone.md - Helicone AI のオブザーバビリティのインストール
• references/manual-capture.md - AI オブザーバビリティの手動キャプチャ
• references/basics.md - AI オブザーバビリティの基本
• references/traces.md - トレース
• references/calculating-costs.md - LLM コストの計算
• references/COMMANDMENTS.md - インテグレーションが従うべき、フレームワーク固有のルール

各プロバイダーのリファレンスには、そのプロバイダーまたはフレームワークに固有のインストール手順、SDK のセットアップ、コード例が記載されています。ユーザーのスタックに合ったリファレンスを確認してください。

ユーザーが使用しているプロバイダーが一覧にない場合は、フォールバックとして manual-capture.md を使用してください。あらゆるプロバイダーで使える汎用的なイベントキャプチャの方法を説明しています。

重要な原則

• 環境変数：PostHog と LLM プロバイダーのキーには、必ず環境変数を使用してください。ハードコードは避けてください。
• 変更は最小限に：既存の LLM 呼び出しに LLM アナリティクスを追加してください。既存コードを置き換えたり、再構成したりしないでください。
• すべての生成をトレース：すべての LLM 呼び出しについて、入力トークン数、出力トークン数、モデル名、レイテンシ、コストを記録してください。
• ユーザーに紐付ける：可能な場合は、distinct ID を使って LLM の生成を識別済みユーザーに関連付けてください。
• 一度に扱うプロバイダーは1つ：ユーザーが実際に使用しているプロバイダーのみを計測してください。コードベースに存在しないプロバイダーの計測は追加しないでください。