instrument-metrics

PostHog メトリクスキャプチャの追加

新規または変更したコードに PostHog メトリクスキャプチャ（カウンター、ゲージ、ヒストグラム）を追加するには、このスキルを使用してください。機能の実装後や PR のレビュー後に主要な操作が計測されているか確認する場合、ユーザーからメトリクスやカウンターの追加を依頼された場合、または既存のメトリクス計測を PostHog に反映する場合に使用します。あらゆるプラットフォームや言語に対応しています。

対応プラットフォーム：Web（JavaScript）、Node.js、posthog.metrics SDK API を使用する Python、メトリクスエージェントを使用する Kubernetes、OpenTelemetry（OTLP）を使用するあらゆる言語。

手順

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

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

• 言語、フレームワーク、既存のメトリクス設定を検出します。
• 依存関係ファイルとプロジェクトファイル（package.json、requirements.txt、pyproject.toml、go.mod、pom.xml など）を確認します。
• 既存のメトリクス計測を探します。Prometheus クライアント（prom-client、prometheus_client）、StatsD／Datadog クライアント、OpenTelemetry メーター、または OpenTelemetry Collector の設定を確認します。
• PostHog SDK（posthog-js、posthog-node、posthog-python）がすでにインストールされているか確認します。

STEP 2：キャプチャ方法を選択します。

• PostHog SDK がインストールされている（またはそのプラットフォームで利用できる）場合は、posthog.metrics API を使用します。OpenTelemetry パッケージは不要です。該当するプラットフォームのリファレンスを確認してください。
• コードベースですでに OpenTelemetry メトリクスをエクスポートしている場合は、既存の OTLP メトリクスエクスポーター（または Collector）の送信先を PostHog に変更します。「Other Languages」リファレンスを確認してください。エクスポーターの設定以外にアプリケーションコードを変更する必要はありません。
• どちらにも当てはまらない場合は、フォールバックとして「Other Languages」リファレンスを使用します。汎用的な OpenTelemetry の方法が記載されています。

STEP 3：既存のメトリクスと並行して計測を追加します。

• コードベースですでにメトリクスを記録している箇所（Prometheus カウンター、StatsD 呼び出し、OTel インストゥルメント）では、同じメトリクス名と属性を再利用し、既存の呼び出しの隣に PostHog の呼び出しを追加します。既存の計測を削除したり、構成し直したりしないでください。
• 既存ファイルの基本的なアーキテクチャを変更しないでください。追加は最小限かつ対象を絞って行います。
• ファイルを書き込む前に、必ずそのファイルを読み込んでください。

STEP 4：適切な箇所に新しいメトリクスを追加します。

• ユーザーから新しいメトリクスを依頼された場合、または主要な操作が計測されていない場合は、適切な箇所に PostHog メトリクス呼び出しを追加します。重要なフローの成功と失敗をカウントし、外部呼び出しやジョブの時間をヒストグラムで計測し、キューの深さやプールのサイズをゲージで計測します。
• 適切な種類を選択します。増加するだけの値にはカウンター、増減する値にはゲージ、時間などの分布にはヒストグラムを使用します。ヒストグラムには明示的な単位（ms、bytes）を設定します。
• 安定した、説明的なドット区切りの名前（jobs.processed、api.request.duration）を選び、サービス名を設定して各システムを簡単に識別できるようにします。

STEP 5：カーディナリティを低く抑えます。

• route、status、plan、queue などの属性は適しています。ユーザー ID、セッション ID、リクエスト ID、タイムスタンプは使用しないでください。属性の組み合わせが一意であるごとに、新しい系列が作成されます。
• ユーザー単位またはリクエスト単位の詳細が必要な場合、それはメトリクスではなく PostHog のログまたはトレースで扱います。 STEP 6: 環境変数を設定します。（PostHog SDK がすでに設定されている場合はスキップしてください。posthog.metrics は SDK の既存のプロジェクトトークンを再利用します。）
• プロジェクトに 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 と決めつけないでください。
• OTLP メトリクスエンドポイントには、上記で確認したリージョンに合わせて、https://us.i.posthog.com/i/v1/metrics（US）または https://eu.i.posthog.com/i/v1/metrics（EU）を使用し、プロジェクトトークンを Authorization: Bearer ヘッダーに指定します。
• フレームワークの命名規則に従って、これらの値を適切な環境変数ファイルに書き込みます。
• 値をハードコードせず、コード内でこれらの環境変数を参照します。

STEP 7: メトリクスが届くことを確認します。

• 短時間で終了するプロセス（スクリプト、cron ジョブ、サーバーレス）の場合は、終了前にフラッシュします（posthog.metrics.flush()、または OTel プロバイダーの forceFlush()／shutdown()）。
• PostHog のサイドバーで「Metrics」を開き、名前選択メニューからメトリクスを選択します。送信から 1 分以内にデータポイントが表示されるはずです。

参照ファイル

• references/javascript.md - JavaScript（ウェブ）でのメトリクスのインストール
• references/nodejs.md - Node.js でのメトリクスのインストール
• references/python.md - Python でのメトリクスのインストール
• references/kubernetes.md - Kubernetes でのメトリクスのインストール
• references/other.md - その他の言語でのメトリクスのインストール
• references/start-here.md - メトリクスを始める
• references/basics.md - メトリクスが必要な理由
• references/architecture.md - メトリクスの仕組み
• references/COMMANDMENTS.md - インテグレーションが従う必要のあるフレームワーク固有のルール

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

主な原則

• 環境変数：PostHog のキーと OpenTelemetry のエンドポイントには、必ず環境変数を使用します。ハードコードしないでください。
• 変更は最小限に：既存のメトリクスに加えて、PostHog のメトリクス収集を追加します。既存の計装を置き換えたり、再構成したりしないでください。
• SDK を優先：PostHog SDK がある場合、posthog.metrics に新しいパッケージや追加の認証は必要ありません。OTLP の設定は、すでに OpenTelemetry を導入しているコードベースや、SDK がサポートされていない言語に限って使用します。
• カーディナリティを低く保つ：属性の組み合わせが一意であるごとに、新しい系列が作成されます。ルート、ステータス、プランなど、値の範囲が限定されたディメンションを付与し、ユーザー ID、セッション ID、リクエスト ID は決して付与しないでください。