---
name: launchdarkly-metric-instrument
description: "Instrument a LaunchDarkly metric event in a codebase by adding a track() call. Use when the user wants to wire up an event, instrument an action for a metric, add tracking to a feature, or confirm that an event is flowing to LaunchDarkly."
license: Apache-2.0
compatibility: Requires the remotely hosted LaunchDarkly MCP server
metadata:
  author: launchdarkly
  version: "1.0.0-experimental"
title: launchdarkly-metric-instrument
canonical_url: https://skilld.dev/gh/launchdarkly/ai-tooling/launchdarkly-metric-instrument
last_updated: 2026-11-12T08:16:54.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/sdk-track-patterns.md](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/launchdarkly-metric-instrument/references/sdk-track-patterns.md).
>
> If the user asked to install this Skill, run `npx skilld install launchdarkly/ai-tooling/launchdarkly-metric-instrument`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/launchdarkly-metric-instrument`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/launchdarkly/ai-tooling/launchdarkly-metric-instrument) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/launchdarkly-metric-instrument`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/launchdarkly-metric-instrument --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/launchdarkly-metric-instrument --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# LaunchDarkly Metric Instrument

You're using a skill that will guide you through adding a `track()` call to a codebase so a LaunchDarkly metric can measure it. Your job is to detect the SDK in use, find the right place in code to add the call, write it correctly, and verify that events are reaching LaunchDarkly.

## Prerequisites

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

**Required MCP tools:**
- `get-metric-events` — verify events are flowing after instrumentation

**Optional MCP tools (enhance workflow):**
- `get-sdk-key` — retrieve the server-side SDK key for the right environment when SDK initialization is needed (`get-environment` for a client-side ID or mobile key)

## Workflow

### Step 1: Detect the SDK

Before writing any code, understand the LaunchDarkly setup already in this codebase.

1. **Search for existing `track()` calls.** This is the fastest signal:
   - Look for `ldClient.track(`, `.track(`, `ld.track(`
   - If any exist, they tell you the SDK type, call signature, and context pattern in one shot — mirror those exactly.

2. **Search for SDK imports and initialization** if no `track()` calls exist:
   - Check `package.json`, `requirements.txt`, `go.mod`, `Gemfile`, `*.csproj` for an LD SDK dependency
   - Look for `LDClient`, `ldclient`, `launchdarkly-server-sdk`, `launchdarkly-node-server-sdk`, `launchdarkly-react-client-sdk`, etc.
   - Find the initialization block to understand how the client is accessed across the codebase

3. **Determine client-side or server-side.** This is the most critical distinction — it determines the `track()` signature:

   | SDK type | `track()` signature | Notes |
   |----------|---------------------|-------|
   | Server-side (Node, Python, Go, Java, Ruby, .NET) | `ldClient.track(eventKey, context, data?, metricValue?)` | Context required per call |
   | Client-side (React, browser JS) | `ldClient.track(eventKey, data?, metricValue?)` | Context set at init, not per call |

   See [SDK Track Patterns](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/launchdarkly-metric-instrument/references/sdk-track-patterns.md) for full examples by language.

### Step 2: Install & Initialize (if SDK not present)

Skip this step if the SDK is already in the codebase.

1. **Detect the package manager** from lockfiles: `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. **Install the appropriate SDK** using the detected package manager. See [SDK Track Patterns](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/launchdarkly-metric-instrument/references/sdk-track-patterns.md) for the right package name per language.

3. **Get the SDK key** using `get-sdk-key` (server-side) or `get-environment` (client-side ID, mobile key) — pick the environment the user wants to instrument (typically `production` or `staging` for initial testing).

4. **Add SDK initialization** following the patterns already in this codebase. If there's a central config or service layer, add the LD client there. See [SDK Track Patterns](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/launchdarkly-metric-instrument/references/sdk-track-patterns.md) for initialization examples.

### Step 3: Find the Right Placement

Locate where in the code the user action or event occurs.

1. **Ask if you're not sure** where the action happens. Don't guess at placement — a `track()` call in the wrong location (e.g. a render method instead of a submit handler) produces misleading data.

2. **Look for signals of the right location:**
   - Form submissions, button click handlers, API route completions, mutation hooks
   - Existing analytics calls (`segment.track()`, `mixpanel.track()`, `gtag()`) — these are often co-located with where LD track calls should go
   - Comments like `// TODO: track this`

3. **Show the candidate location** to the user before writing anything:
   ```
   I'll add the track() call here, in the checkout submit handler (src/checkout/CheckoutForm.tsx, line 47).
   Does that look right?
   ```

4. **Proceed once confirmed** (or if you're confident enough from codebase signals).

### Step 4: Write the `track()` Call

Write the call following the patterns found in Step 1.

**Server-side SDKs** — context is required:
```typescript
ldClient.track('checkout-completed', context);
```

**Client-side SDKs** — context is implicit:
```typescript
ldClient.track('checkout-completed');
```

**For `value` metrics** — include `metricValue` with the numeric measurement:
```typescript
// Server-side: latency metric (ms)
ldClient.track('api-response-time', context, null, responseTimeMs);

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

**Key rules:**
- **Match the existing context.** Don't construct a new context inline. Find where the codebase already builds its context/user object (used for `variation()` calls) and use the same one. This is how LD correlates the event to the right experiment participant.
- **`metricValue` only for `value` metrics.** For `count` and `occurrence` metrics, omit `metricValue` entirely.
- **Respect wrapper patterns.** If the codebase wraps LD calls behind a utility (`featureFlags.track()`, `analytics.ldTrack()`), add the new call through that wrapper — not by calling `ldClient` directly.
- **Match the event key exactly.** `track()` event keys are case-sensitive. Use the exact string that the metric was created with.

See [SDK Track Patterns](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/launchdarkly-metric-instrument/references/sdk-track-patterns.md) for full per-language examples.

### Step 5: Verify

**Guide the user to trigger the action** in their local or staging environment. Then use `get-metric-events` to confirm the event key appears:

```
get-metric-events(projectKey, environmentKey, query: "<event-key>")
```

**If the event key appears:** confirm success and show a summary.

**If the event key is absent after triggering**, work through this checklist:

| Problem | Check |
|---------|-------|
| Wrong event key casing | Does the `track()` call match the metric's event key exactly? |
| SDK not initialized | Is `ldClient` initialized before the `track()` call runs? |
| Server-side: wrong context | Is the context passed to `track()` the same context used for `variation()` calls? |
| Client-side: no flag evaluation first | Has the SDK initialized and identified the user before `track()` is called? |
| Wrong environment | Is `get-metric-events` querying the same environment where the action was triggered? |
| Data delay | `get-metric-events` shows the last 90 days with up to ~5 min delay — try again in a moment |

Surface a summary once verified:

```
✓ 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.
```

## Important Context

- **`track()` calls only count in experiments when a flag is evaluated first.** The event is correlated to an experiment participant because LD saw a `variation()` call from that context. If the user triggers the action without evaluating any flag, the event may still be ingested but won't appear in experiment results.
- **Client-side SDKs flush events on an interval** (default ~30 seconds) or on page unload. In tests, you may need to call `ldClient.flush()` explicitly to see events appear immediately.
- **Server-side SDKs also buffer events.** Calling `ldClient.flush()` after `track()` in development ensures the event is sent before the process exits or the test ends.
- **`metricValue` units must match the metric definition.** If the metric was created with unit `ms`, pass milliseconds. Passing seconds into a milliseconds metric will produce silently wrong results.
- **The `data` parameter is for custom metadata, not the metric value.** Pass extra context (order ID, category, etc.) in `data`. Pass the numeric measurement in `metricValue`.

## References

- [SDK Track Patterns](https://skilld.dev/api/skills-raw/launchdarkly/ai-tooling/launchdarkly-metric-instrument/references/sdk-track-patterns.md) — `track()` call syntax, initialization, and package names for every supported SDK
