launchdarkly-metric-instrument

LaunchDarkly メトリクスインストルメンテーション

あなたは、LaunchDarkly メトリクスがそれを測定できるように、コードベースに track() 呼び出しを追加する作業をガイドするスキルを使用しています。あなたの仕事は、使用されている SDK を検出し、コード内で呼び出しを追加する適切な場所を見つけ、正しく記述し、イベントが LaunchDarkly に到達していることを検証することです。

前提条件

このスキルは、リモートでホストされている LaunchDarkly MCP サーバーが環境内で設定されている必要があります。

必須の MCP ツール:

• list-metric-events — インストルメンテーション後にイベントが流れていることを検証します

オプションの MCP ツール（ワークフローを強化します）:

• get-project — SDK の初期化が必要な場合に、適切な環境の SDK キーを取得します

ワークフロー

ステップ 1: SDK を検出する

コードを記述する前に、このコードベースに既にある LaunchDarkly のセットアップを理解してください。

1. 既存の track() 呼び出しを検索します。 これが最も速い手がかりです:

   • ldClient.track(、.track(、ld.track( を探します
   • 存在する場合、それらは SDK の種類、呼び出しシグネチャ、コンテキストのパターンを一度に教えてくれます — それらを正確に踏襲してください。

2. track() 呼び出しが存在しない場合は、SDK のインポートと初期化を検索します:

   • package.json、requirements.txt、go.mod、Gemfile、*.csproj に LD SDK の依存関係がないか確認します
   • LDClient、ldclient、launchdarkly-server-sdk、launchdarkly-node-server-sdk、launchdarkly-react-client-sdk などを探します
   • 初期化ブロックを見つけて、コードベース全体でクライアントにどのようにアクセスしているかを理解します

3. クライアントサイドかサーバーサイドかを判断します。 これが最も重要な区別です — これが track() のシグネチャを決定します:

   SDK の種類	track() シグネチャ	備考
   サーバーサイド（Node、Python、Go、Java、Ruby、.NET）	ldClient.track(eventKey, context, data?, metricValue?)	呼び出しごとにコンテキストが必要
   クライアントサイド（React、ブラウザ JS）	ldClient.track(eventKey, data?, metricValue?)	コンテキストは初期化時に設定され、呼び出しごとではない

   言語別の完全な例については、SDK Track Patterns を参照してください。

ステップ 2: インストールと初期化（SDK が存在しない場合）

SDK がすでにコードベースにある場合は、このステップをスキップしてください。

1. ロックファイルからパッケージマネージャーを検出します: package-lock.json / yarn.lock / pnpm-lock.yaml → npm/yarn/pnpm、Pipfile.lock / poetry.lock → pip/poetry、go.sum → go modules、Gemfile.lock → bundler。

2. 検出したパッケージマネージャーを使用して、適切な SDK をインストールします。 言語ごとの正しいパッケージ名については、SDK Track Patterns を参照してください。

3. get-project を使用して SDK キーを取得します — プロジェクトを取得し、ユーザーがインストルメンテーションしたい環境（通常、初期テストでは production または staging）のキーを選択します。

4. このコードベースに既にあるパターンに従って、SDK の初期化を追加します。 中央の設定やサービス層がある場合は、そこに LD クライアントを追加します。初期化の例については、SDK Track Patterns を参照してください。

ステップ 3: 適切な配置を見つける

ユーザーのアクションやイベントがコード内のどこで発生するかを特定します。

1. アクションがどこで発生するか確信が持てない場合は尋ねてください。 配置を推測しないでください — 誤った場所（たとえば、送信ハンドラーではなくレンダーメソッド）での track() 呼び出しは、誤解を招くデータを生成します。

2. 適切な場所の手がかりを探します:

   • フォームの送信、ボタンのクリックハンドラー、API ルートの完了、ミューテーションフック
   • 既存のアナリティクス呼び出し（segment.track()、mixpanel.track()、gtag()） — これらは多くの場合、LD の track 呼び出しを配置すべき場所と同じ場所にあります
   • // TODO: track this のようなコメント

3. 何も記述する前に、候補の場所をユーザーに示します:

   I'll add the track() call here, in the checkout submit handler (src/checkout/CheckoutForm.tsx, line 47).
   Does that look right?
   

4. 確認が取れたら進めます（または、コードベースの手がかりから十分に確信がある場合）。

ステップ 4: track() 呼び出しを書く

ステップ 1 で見つけたパターンに従って呼び出しを書きます。

サーバー側 SDK — context が必須です:

ldClient.track('checkout-completed', context);

クライアント側 SDK — context は暗黙的です:

ldClient.track('checkout-completed');

value メトリクスの場合 — 数値の測定値を metricValue に含めます:

// Server-side: latency metric (ms)
ldClient.track('api-response-time', context, null, responseTimeMs);

// Client-side: revenue metric
ldClient.track('purchase-completed', { orderId }, purchaseAmountUSD);

重要なルール:

• 既存の context に合わせる。 新しい context をインラインで構築しないでください。コードベースがすでに context/ユーザーオブジェクトを構築している箇所（variation() 呼び出しで使用されるもの）を見つけ、同じものを使用します。これにより、LD はイベントを正しい実験参加者に関連付けます。
• metricValue は value メトリクスにのみ使用します。 count および occurrence メトリクスでは、metricValue を完全に省略してください。
• ラッパーパターンを尊重する。 コードベースが LD 呼び出しをユーティリティ（featureFlags.track()、analytics.ldTrack()）の背後でラップしている場合は、ldClient を直接呼び出すのではなく、そのラッパーを通して新しい呼び出しを追加してください。
• イベントキーを正確に一致させる。 track() のイベントキーは大文字と小文字を区別します。メトリクスが作成されたときとまったく同じ文字列を使用してください。

言語ごとの完全な例については、SDK Track パターンを参照してください。

ステップ 5: 検証

ユーザーにローカル環境またはステージング環境でアクションをトリガーするよう案内します。 その後、list-metric-events を使用してイベントキーが表示されることを確認します:

list-metric-events(projectKey, environmentKey)

イベントキーが表示される場合: 成功を確認し、サマリーを表示します。

トリガー後にイベントキーが表示されない場合、次のチェックリストを順に確認してください:

問題	確認事項
イベントキーの大文字と小文字が間違っている	track() 呼び出しはメトリクスのイベントキーと正確に一致していますか？
SDK が初期化されていない	track() 呼び出しが実行される前に ldClient は初期化されていますか？
サーバー側: context が間違っている	track() に渡された context は、variation() 呼び出しで使用されたものと同じ context ですか？
クライアント側: 最初にフラグ評価がない	track() が呼び出される前に、SDK が初期化されユーザーを識別していますか？
環境が間違っている	list-metric-events は、アクションがトリガーされたのと同じ環境をクエリしていますか？
データの遅延	list-metric-events は直近 90 日間を最大約 5 分の遅延で表示します — 少し待ってから再試行してください

検証が完了したらサマリーを表示します:

✓ Event flowing: checkout-completed
  Seen in: production
  
Next: this event is now ready to back a metric. Use the metric-create skill to set one up,
or attach an existing metric to your experiment.

重要なコンテキスト

• track() 呼び出しは、最初にフラグが評価された場合にのみ実験でカウントされます。 LD がその context からの variation() 呼び出しを確認したため、イベントは実験参加者に関連付けられます。ユーザーがフラグを評価せずにアクションをトリガーした場合、イベントは取り込まれるかもしれませんが、実験結果には表示されません。
• クライアント側 SDK は一定間隔（デフォルトで約 30 秒）またはページのアンロード時にイベントをフラッシュします。 テストでは、イベントがすぐに表示されるのを確認するために ldClient.flush() を明示的に呼び出す必要がある場合があります。
• サーバー側 SDK もイベントをバッファリングします。 開発中に track() の後に ldClient.flush() を呼び出すことで、プロセスの終了やテストの終了前にイベントが送信されることを保証します。
• metricValue の単位はメトリクス定義と一致する必要があります。 メトリクスが単位 ms で作成された場合は、ミリ秒を渡してください。ミリ秒のメトリクスに秒を渡すと、気づかれないまま誤った結果が生成されます。
• data パラメーターはカスタムメタデータ用であり、メトリクス値用ではありません。 追加のコンテキスト（注文 ID、カテゴリなど）は data に渡してください。数値の測定値は metricValue に渡してください。

参照

• SDK Track パターン — サポートされているすべての SDK の track() 呼び出し構文、初期化、およびパッケージ名