launchdarkly-metric-create

LaunchDarkly メトリクスの作成

あなたは、LaunchDarkly メトリクスの作成をガイドするスキルを使用しています。カスタムメトリクスの場合、イベントを流し始めることが最優先です — メトリクスを作成する前に。あなたの役割は、適切なメトリクスの種類を判断し、イベントがまだ流れていない場合は計装し（SDK のセットアップや環境の接続を含む）、重複を確認し、メトリクス設定を提案し、明示的な確認を得てから、作成および検証することです。

前提条件

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

必要な MCP ツール:

• create-metric — メトリクスを作成します
• get-metric — 作成後に検証します
• get-environment — 計装時にクライアントサイド SDK キーを取得します

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

• list-metrics — 同じイベントキーを持つ既存のメトリクスを確認し、命名規則を把握します
• list-metric-events — 特定のイベントキーを採用する前に、どのイベントキーに最近のアクティビティがあるかを発見します（カスタムメトリクスのみ）

2 つの異なる「プロジェクト」 — 絶対に混同しないでください

ユーザーは、どちらも「プロジェクト」と呼ばれる、完全に別々の 2 つのものを扱います。常にこれらを区別しておく必要があります:

	それが何か	ユーザーがそれをどう呼ぶか	あなたがそれをどう扱うか
LaunchDarkly プロジェクト	メトリクスが作成される、ユーザーの LD アカウント内のプロジェクト	通常は環境名やチーム名のように聞こえます: my-app、anthony-agent-dev-5000、production	すべての MCP ツール呼び出しに projectKey として渡します
ローカルコードベース	あなたが track() 呼び出しで計装する、ディスク上の開発者のアプリケーション	多くの場合、フォルダ名、リポジトリ名、アプリ名です: checkout_proj、frontend、my-react-app	ソースファイルを見つけて編集するために使用します

ユーザー入力からこれらを判別するためのルール:

• ユーザーが 「X にある自分のアプリケーション」、「自分のコードベース」、「自分のリポジトリ」 と言った場合 → 彼らは ローカルコードベース を意味しています。X はフォルダパスまたはプロジェクト名であり、LaunchDarkly のキーではありません。
• ユーザーが 「X に追加して」、「LaunchDarkly で」、「自分の LD プロジェクト」 と言った場合 → 彼らは LaunchDarkly プロジェクト を意味しています。X は API 呼び出し用の projectKey です。
• ユーザーはローカルコードベースを checkout_proj と名付けつつ、LaunchDarkly プロジェクトは anthony-agent-dev-5000 であることがあります。これらは無関係です。
• ローカルコードベース名が LaunchDarkly プロジェクトキーであると決して仮定しないでください。 どちらがどちらか不明な場合は、直接尋ねてください: 「確認させてください — あなたの LaunchDarkly プロジェクトキーは何ですか？（これはローカルアプリ名とは異なります — LD UI の Account Settings > Projects で確認できます。）」

両方が必要な場合（例: 計装を伴うカスタムメトリクス）、進める前にそれぞれを明示的に確認してください。

ワークフロー

ステップ 1: メトリクスの種類を判断する

LaunchDarkly には 3 つのメトリクスの種類があります。何よりも先に適切なものを選んでください。

種類	イベントの収集方法	必要なもの
custom	開発者がコード内で ldClient.track(eventKey) を呼び出します	eventKey
pageview	ユーザーが一致する URL を訪問すると自動的に発火します — SDK 呼び出しは不要です	urls（URL マッチルール）
click	ユーザーが一致する URL 上で CSS セレクターをクリックすると自動的に発火します — SDK 呼び出しは不要です	urls + selector

判断ルール:

• ユーザーが「誰かがページを閲覧したとき / URL を訪問したときにトラッキングしたい」と言った場合 → pageview（推奨 — 計装が不要です）
• ユーザーが「誰かがボタン / リンクをクリックしたときにトラッキングしたい」と言った場合 → click
• ユーザーが「カスタムイベントをトラッキングしたい」と言った場合、または track() 呼び出しに言及した場合 → custom

pageview または click が機能する場合、custom よりもそれを提案してください — コード変更が不要です。

ステップ 2: データソースを解決する

pageview および click メトリクスの場合:

• 一致させる URL を尋ねます。URL 一致ルールの kind を確認します:
  • substring — URL にこの文字列が含まれる (最も一般的)
  • exact — URL が完全に一致する必要がある
  • canonical — 正規 URL に一致する
  • regex — 完全な正規表現パターン
• click メトリクスの場合は、CSS セレクター (例: .checkout-btn、#submit) も尋ねます。
• list-metric-events はスキップします — これらのメトリクスはイベントキーを使用しません。
• ステップ 3 に進みます。

custom メトリクスの場合 — まずイベントを確認し、必要なら計測を設定します:

list-metric-events をすぐに呼び出して、どのイベントキーがすでに送信されているかを確認します:

list-metric-events(projectKey, environmentKey?)

ケース A — イベントキーがすでにリストにある場合: ユーザーとキーを確認し、ステップ 3 に進みます。計測の設定は不要です。

ケース B — イベントキーがリストにない場合: そのメトリクスはイベントがなければ何も測定できません。メトリクスを作成する前に、今すぐイベントを計測できるようにしてください。 単に警告して続行するかどうかを尋ねるのではなく、計測の設定をデフォルトの次のアクションとして扱ってください。

以下の計測サブワークフローに従い、その後 list-metric-events を再確認して、ステップ 3 に進む前にイベントが送信されていることを確認します。ユーザーが明示的に、先にメトリクスを作成してイベントの接続は後で行いたいと述べた場合にのみ、計測の設定をスキップしてください — その場合は、最後に、イベントがトラッキングされるまでそのメトリクスはデータを生成しないことをユーザーに思い出させてください。

ステップ 2b: イベントを計測する (イベントが送信されていない場合)

このサブワークフローでは、track() 呼び出しをコードベースに追加し、アプリを正しい LaunchDarkly 環境に接続します。メインワークフローに戻る前に、すべてのステップを完了してください。

1. コードベース内の適切な場所を見つけます。 イベントが自然に発生する関数またはハンドラー (例: チェックアウトの送信ハンドラー、フォーム送信のコールバック) を特定します。変更を加える前に、関連するソースファイルを読んで既存の構造を理解します。

2. イベントキーを決定します。 ユーザーが指定していない場合は、コードが行っている内容に合った説明的なケバブケースのキー (例: checkout-completed、signup-submitted) を提案します。使用する前にユーザーに確認します。

3. クライアントサイド SDK キーを取得します。 接続したい環境 (例: 「test」、「production」、「staging」) をユーザーに尋ねます — 環境名だけでかまいません。その後、次を呼び出します:

get-environment(projectKey, environmentKey)

レスポンスの clientSideId を使用します。

4. 環境ファイルを書き込みます。 .env ファイル (または同等のもの — .env.local、.env.development など) がすでに存在するかどうかを確認します。

• ファイルが存在しない場合は、作成します。
• ファイルが存在し、すでにキーが含まれている場合 (例: VITE_LD_CLIENT_SIDE_ID)、保存されている値と get-environment が返した clientSideId を比較します。それらが異なる場合は、その不一致をユーザーに提示します:

  「あなたの .env にはすでに VITE_LD_CLIENT_SIDE_ID=<old> がありますが、get-environment は <env> 環境に対して <new> を返しました。更新しますか?」 古い値を黙って保持しないでください — クライアントサイド ID が一致しない場合、イベントは誤ったプロジェクトまたは環境に送信されます。

• ファイルが存在するがキーがない場合は、他の値を変更せずに追加します。

プロジェクトのビルドツールに適した変数名を使用します (例: Vite なら VITE_LD_CLIENT_SIDE_ID、CRA なら REACT_APP_LD_CLIENT_SIDE_ID、Next.js なら NEXT_PUBLIC_LD_CLIENT_SIDE_ID)。

4b. ユーザーが app.launchdarkly.com を使用していない場合は、SDK ベース URL を設定します。 SDK はすべてのトラフィックに対してデフォルトで app.launchdarkly.com を使用します。ユーザーが別の LaunchDarkly デプロイメント (例: catamorphic のような内部ステージング環境、または専用インスタンス) を使用している場合、イベントとフラグ評価は気づかないうちに誤ったホストに送信されます。

これは、MCP API レスポンス内の _links や UI URL を調べることで検出します — それらが app.launchdarkly.com 以外のホストを指している場合、本番以外のデプロイメントを使用しています。判断に迷ったら、次のように尋ねます:

「app.launchdarkly.com に接続していますか、それとも別の LaunchDarkly インスタンスに接続していますか? (例: 内部環境やステージング環境)」 標準以外のホストを使用している場合は、.env ファイルに 3 つの追加変数を追加します。

VITE_LD_BASE_URL=https://<their-host>
VITE_LD_STREAM_URL=https://clientstream.<their-host-domain>
VITE_LD_EVENTS_URL=https://events.<their-host-domain>

そして、初期化時にそれらを SDK の options に渡します。

asyncWithLDProvider({
  clientSideID,
  context: { kind: 'user', anonymous: true },
  options: {
    baseUrl: import.meta.env.VITE_LD_BASE_URL,
    streamUrl: import.meta.env.VITE_LD_STREAM_URL,
    eventsUrl: import.meta.env.VITE_LD_EVENTS_URL,
  },
})

app.launchdarkly.com を使用している場合は、options ブロックを完全に省略してください。デフォルト設定が正しいため、追加の設定は不要です。

5. SDK がまだインストールされていない場合は、インストールして初期化します。 package.json（または同等の依存関係ファイル）に既存の LD SDK があるか確認してください。見つからない場合は、プロジェクトのスタックに適したものをインストールします。

• React → launchdarkly-react-client-sdk
• ブラウザ JS → launchdarkly-js-client-sdk
• Node.js サーバー → @launchdarkly/node-server-sdk

アプリのエントリーポイントで SDK を初期化します（例: React ルートを LDProvider でラップする、サーバーのエントリーで LDClient.init() を設定するなど）。env ファイルからクライアントサイド ID を渡してください。アプリがすでにユーザーコンテキストを管理している場合を除き、デフォルトとして匿名ユーザー／コンテキストを使用します。

6. track() 呼び出しを追加します。 ステップ 1 で特定した箇所で、アクションの完了直前または直後に呼び出しを追加します。

• カウント／発生メトリクス: ldClient.track('event-key')
• 値メトリクス: ldClient.track('event-key', null, numericValue)

クライアントがまだ初期化されていない可能性があるクライアントサイドコードでは、オプショナルチェーン（ldClient?.track(...)）を使用してください。

7. イベントが流れていることを確認します。 計装の変更が完了したら、アプリを実行してイベントを少なくとも 1 回トリガーするようユーザーに促してください。その後、再度 list-metric-events を呼び出して、メトリクスの作成に進む前にキーが表示されることを確認します。

ステップ 3: 既存のメトリクスを確認する

何かを作成する前に、list-metrics を使用してプロジェクトをスキャンします。

1. 重複がないか確認します。 同じイベントキー、URL パターン、または類似した名前のメトリクスを検索します。同じものを測定する 2 つ目のメトリクスを作成しないでください。代わりに、既存のメトリクスを指摘し、それを再利用するかどうかをユーザーに尋ねてください。
2. 命名規則を把握します。 メトリクスキーは kebab-case ですか、それとも snake_case ですか？ 共通のタグパターンはありますか？ 既存のものに合わせてください。
3. タグの分類体系を理解します。 team:growth、area:checkout、type:guardrail などのタグがすでに存在する可能性があります。ユーザーが説明した内容に基づいて、関連するタグを提案してください。

ステップ 4: メトリクス設定を提案する

API を呼び出す前に、提案する設定を平易な言葉で提示し、ユーザーが確認または編集できるようにします。

測定タイプを決定します。 適切な選択は、ユーザーが何を明らかにしようとしているのか、そしてそのメトリクスをどのように使用するのか (実験、段階的ロールアウト、リリースポリシーなど) によって異なります。決めつけないでください。 イベントがユーザーによって繰り返し実行できるもの (クリック、カートへの追加、ページ閲覧など) である場合は、提案する前に必ず尋ねてください:

「このイベントが合計で何回発生するかを測定したいですか (count)、それともユーザーの何パーセントが少なくとも 1 回トリガーしたかを測定したいですか (occurrence)？」

質問はユーザーのコンテキストに結び付けてください:

• 実験 — コンバージョン目標では occurrence が一般的です (処置によって X を行うユーザーが増えたか？)。エンゲージメントやボリュームの目標では count のほうが適しています (処置によって総アクション数が増えたか？)
• 段階的ロールアウト / リリースポリシー — エラー率のガードレールでは occurrence が典型的です (ユーザーのどの割合がエラーに遭遇したか？)。絶対的なボリュームのガードレールでは count が適しています (総エラーイベント数)
• ユーザーが明示的に「ユーザーのパーセント」または「コンバージョン率」と言った場合 → occurrence
• ユーザーが明示的に「回数」または「総イベント数」と言った場合 → count

コンテキストから意図が明確な場合 (例: 「API レイテンシ」→ value、「エラー率」→ count、「サインアップ コンバージョン」→ occurrence) にのみ、質問を省略してください。

ユーザーが測定したいもの	測定タイプ	意味
イベントが発生した合計回数	count	分析単位ごとの生のイベント数
各ユーザーがイベントをそもそもトリガーしたかどうか	occurrence	コンバージョン / バイナリ (発生したか？)
イベントに付随する数値	value	レイテンシ、収益、スコアなど

成功基準を決定します:

• 高いほうが良い → HigherThanBaseline (コンバージョン率、収益、エンゲージメント)
• 低いほうが良い → LowerThanBaseline (レイテンシ、エラー率、直帰率)

ユーザーの意図が明確な場合は、一般的なテンプレートをデフォルトとして使用します:

ユーザーの意図	kind	測定タイプ	成功基準	単位
ページ訪問 / 閲覧率	pageview	occurrence	HigherThanBaseline	—
ボタン / リンクのクリック率	click	occurrence	HigherThanBaseline	—
API レイテンシ / ページ読み込み時間	custom	value (平均)	LowerThanBaseline	ms
サインアップ / コンバージョン率	custom	occurrence	HigherThanBaseline	—
エラー数 / エラー率	custom	count	LowerThanBaseline	—
ユーザーあたりの収益	custom	value (合計)	HigherThanBaseline	USD

作成する前に提案する設定を提示します — 黙って API を発火させないでください:

Proposed metric:
  Key:              checkout-page-viewed
  Name:             Checkout Page Viewed
  Kind:             pageview (fires automatically on URL visit — no code change needed)
  URLs:             substring match on "/checkout"
  Measure type:     occurrence (did each user visit the page?)
  Success criteria: HigherThanBaseline

Proceed, or would you like to change anything?

ここで停止します。 いかなる API も呼び出さないでください。ステップ 5 に進まないでください。他の何かを行う前に、ユーザーが明示的に確認するのを待ってください。create-metric を呼び出す前に、ユーザーが承認 (例: 「はい」、「問題なさそうです」、「進めてください」) で応答する必要があります。提案する設定に何らかの曖昧さがある場合 — たとえば sum と average のどちらを選ぶか、またはイベントキー名など — その質問を提案の一部として尋ね、続行する前に回答を待ってください。

ステップ 5: メトリクスを作成する

ユーザーがステップ 4 で提案する設定を明示的に確認した場合にのみ進めてください。 まだ確認を受け取っていない場合は、戻って待ってください。

ユーザーが確認したら、create-metric を呼び出します。このツールは measureType から基盤となる API フィールドへの変換を処理します — isNumeric や unitAggregationType を直接渡す必要はありません。

create-metric(
  projectKey,
  key,
  name,
  kind,              // "custom" | "pageview" | "click"
  eventKey?,         // only for kind="custom"
  urls?,             // only for kind="pageview" or "click": [{ kind, url }]
  selector?,         // only for kind="click": CSS selector string
  measureType,       // "count" | "occurrence" | "value"
  successCriteria,   // "HigherThanBaseline" | "LowerThanBaseline"
  valueAggregation?, // only for measureType="value": "average" (default) or "sum"
  unit?,             // display label: "ms", "USD", etc.
  description?,
  tags?
)

ステップ 6: 検証

get-metric を使用して、メトリクスが正しい構成で作成されたことを確認します:

1. キーと名前が要求どおりであること。
2. kind が正しいこと — custom、pageview、または click。
3. measureType が正しいこと — isNumeric だけでなく、measureType フィールドを読み返して再確認してください。
4. eventKey / urls / selector が意図した値に設定されていること。
5. successCriteria が正しいこと。

ユーザーに概要を提示します:

✓ Metric created: checkout-page-viewed
  Kind:     pageview (auto-tracked on URL visit)
  URLs:     substring "/checkout"
  Measures: occurrence (conversion rate)
  Goal:     Higher is better

View in LaunchDarkly: {_links.ui from the create-metric response}

create-metric ツールは、使用中の環境に対応する正しい URL を含む _links.ui フィールドを返します。常にその値を使用してください — app.launchdarkly.com をハードコードしないでください。

Measure Type リファレンス

create-metric ツールは、measureType を内部的に LD API のフィールドへ変換します。isNumeric や unitAggregationType を直接設定する必要はありません。

measureType	isNumeric	unitAggregationType	用途
count	false	sum	生のイベント数 — エラー率、クリック数
occurrence	false	average	コンバージョン — ユーザーがその行動を行ったかどうか
value (average)	true	average	ユーザーごとの平均 — 平均レイテンシ、平均セッション時間
value (sum)	true	sum	ユーザーごとの合計 — 総売上、購入アイテム総数

value メトリクスの場合、valueAggregation はデフォルトで "average" になります。売上や累積合計には valueAggregation: "sum" を渡してください。

重要なコンテキスト

• 可能な場合は custom よりも pageview と click を優先してください。 これらは SDK の計装が不要で、ブラウザ環境で自動的に動作します。
• イベントキーは大文字と小文字を区別します。 checkout-completed と Checkout-Completed は異なるイベントです。track() 呼び出しに表示されるキーと正確に一致させてください。
• イベントのないカスタムメトリクスはデータを生成しません。 カスタムメトリクスは、そのイベントキーが本番環境(または該当する環境)で実際にトラッキングされて初めて役立ちます。イベントを計装する前にメトリクスを作成した場合は、ユーザーにその旨を伝えてください。
• メトリクスキーは変更できません。 一度作成すると、メトリクスのキーは変更できません。慎重に選択してください。
• メトリクスはプロジェクト単位です。 あるプロジェクトで作成されたメトリクスは、別のプロジェクトでは表示されません。projectKey が実験またはフィーチャーフラグが存在する場所と一致していることを確認してください。
• 実験ごとにプライマリメトリクスは 1 つです。 このメトリクスを実験にアタッチする際は、それがプライマリメトリクス(成功か失敗かを決定するもの)なのか、セカンダリメトリクス(ガードレールや補助的なシグナル)なのかを明確にしてください。実験の設定については LaunchDarkly のドキュメントを参照してください。