Launchdarkly Metric Create

LaunchDarkly Metric Create

You're using a skill that will guide you through creating a LaunchDarkly metric. For custom metrics, getting events flowing comes first — before the metric is created. Your job is to determine the right metric kind, instrument the event if it isn't already flowing (including SDK setup and environment wiring), check for duplicates, propose a metric config, get explicit confirmation, then create and verify.

Prerequisites

This skill requires the remotely hosted LaunchDarkly MCP server to be configured in your environment.

Required MCP tools:

• create-metric — create the metric
• get-metric — verify it after creation
• get-environment — fetch the client-side SDK key when instrumenting

Optional MCP tools (enhance workflow):

• list-metrics — check for existing metrics with the same event key and understand naming conventions
• list-metric-events — discover which event keys have recent activity before committing to one (custom metrics only)

Two Different "Projects" — Never Confuse Them

Users work with two completely separate things that both get called "project." You must keep these distinct at all times:

Rules for resolving these from user input:

• If the user says "my application at X" or "my codebase" or "my repo" → they mean the local codebase. X is a folder path or project name, not a LaunchDarkly key.
• If the user says "add it to X" or "in LaunchDarkly" or "my LD project" → they mean the LaunchDarkly project. X is the projectKey for API calls.
• A user can name their local codebase checkout_proj while their LaunchDarkly project is anthony-agent-dev-5000. These are unrelated.
• Never assume the local codebase name is a LaunchDarkly project key. If you're unsure which is which, ask directly: "Just to confirm — what's your LaunchDarkly project key? (This is different from your local app name — you can find it in the LD UI under Account Settings > Projects.)"

When both are needed (e.g. for a custom metric with instrumentation), confirm each explicitly before proceeding.

Workflow

Step 1: Determine the Metric Kind

LaunchDarkly has three metric kinds. Choose the right one before anything else.

Decision rules:

• User says "track when someone views a page / visits a URL" → `pageview` (preferred — no instrumentation required)
• User says "track when someone clicks a button / link" → `click`
• User says "track a custom event" or references a track() call → `custom`

When pageview or click would work, suggest it over custom — it requires no code changes.

Step 2: Resolve the Data Source

For `pageview` and `click` metrics:

• Ask for the URL(s) to match. Confirm the kind of URL match rule:
• substring — URL contains this string (most common)
• exact — URL must match exactly
• canonical — matches the canonical URL
• regex — full regex pattern
• For click metrics, also ask for the CSS selector (e.g. .checkout-btn, #submit).
• Skip list-metric-events — these metrics don't use event keys.
• Skip to Step 3.

For `custom` metrics — check events first, instrument if needed:

Call list-metric-events immediately to see which event keys are already flowing:

list-metric-events(projectKey, environmentKey?)

Case A — the event key is already in the list: Confirm the key with the user and proceed to Step 3. No instrumentation needed.

Case B — the event key is NOT in the list: The metric can't measure anything without events. Instrument the event now before creating the metric. Do not simply warn and ask whether to proceed — treat instrumentation as the default next action.

Follow the instrumentation sub-workflow below, then re-check list-metric-events to confirm events are flowing before moving to Step 3. Only skip instrumentation if the user explicitly says they want to create the metric first and wire the event up later — in that case, remind them at the end that the metric will produce no data until the event is tracked.

Step 2b: Instrument the Event (when events aren't flowing)

This sub-workflow gets a track() call into the codebase and connects the app to the right LaunchDarkly environment. Complete all steps before returning to the main workflow.

1. Find the right place in the codebase. Locate the function or handler where the event naturally occurs (e.g. a checkout submit handler, a form submission callback). Read the relevant source files to understand the existing structure before making changes.

2. Determine the event key. If the user hasn't specified one, propose a descriptive kebab-case key that matches what the code is doing (e.g. checkout-completed, signup-submitted). Confirm with the user before using it.

3. Fetch the client-side SDK key. Ask the user which environment they want to connect to (e.g. "test", "production", "staging") — just the environment name. Then call:

get-environment(projectKey, environmentKey)

Use the clientSideId from the response.

4. Write the environment file. Check whether a .env file (or equivalent — .env.local, .env.development, etc.) already exists.

• If the file does not exist, create it.
• If the file exists and already contains the key (e.g. VITE_LD_CLIENT_SIDE_ID), compare the stored value to the clientSideId returned by get-environment. If they differ, surface the discrepancy to the user: > "Your .env already has VITE_LD_CLIENT_SIDE_ID=<old>, but get-environment returned <new> for the <env> environment. Should I update it?" Do not silently keep the old value — a mismatched client-side ID means events will be sent to the wrong project or environment.
• If the file exists but the key is absent, add it without touching other values.

Use the variable name appropriate to the project's build tool (e.g. VITE_LD_CLIENT_SIDE_ID for Vite, REACT_APP_LD_CLIENT_SIDE_ID for CRA, NEXT_PUBLIC_LD_CLIENT_SIDE_ID for Next.js).

4b. Set the SDK base URL if the user is not on app.launchdarkly.com. The SDK defaults to app.launchdarkly.com for all traffic. If the user is on a different LaunchDarkly deployment (e.g. an internal staging environment like catamorphic, or a dedicated instance), events and flag evaluations will silently go to the wrong host.

Detect this by inspecting any _links or UI URLs in MCP API responses — if they point to a host other than app.launchdarkly.com, you are on a non-production deployment. When in doubt, ask:

"Are you connecting to app.launchdarkly.com or a different LaunchDarkly instance? (e.g. an internal or staging environment)"

If they are on a non-standard host, add three additional variables to the .env file:

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>

And pass them to the SDK options at init time: