Launchdarkly Metric Instrument

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:

• list-metric-events — verify events are flowing after instrumentation

Optional MCP tools (enhance workflow):

• get-project — retrieve the SDK key for the right environment when SDK initialization is needed

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:

See SDK Track Patterns 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 for the right package name per language.

3. Get the SDK key using get-project — fetch the project and choose the key for 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 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:

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

Client-side SDKs — context is implicit:

ldClient.track('checkout-completed');

For `value` metrics — include metricValue with the numeric measurement:

// 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 for full per-language examples.

Step 5: Verify

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

list-metric-events(projectKey, environmentKey)

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

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

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 — track() call syntax, initialization, and package names for every supported SDK

SDK Track Patterns

How to call track() in each LaunchDarkly SDK. Use this reference to match the patterns already in use in the codebase — and to add the right call when starting fresh.

The key distinction across all SDKs: server-side SDKs require a context per call; client-side SDKs do not.

---

JavaScript / TypeScript — Node.js (Server-side)

Package: @launchdarkly/node-server-sdk (v9+) or launchdarkly-node-server-sdk (v6–v8)

npm install @launchdarkly/node-server-sdk

import * as ld from '@launchdarkly/node-server-sdk';

const client = ld.init(process.env.LD_SDK_KEY!);
await client.waitForInitialization();

// Count / occurrence metric (no metricValue)
client.track('checkout-completed', context);

// Value metric — pass the measurement as metricValue
client.track('api-response-time', context, null, responseTimeMs);

// With custom data payload
client.track('item-purchased', context, { itemId: 'abc123', category: 'apparel' }, purchaseAmount);

// Flush explicitly in tests / short-lived processes
await client.flush();

---

JavaScript / TypeScript — Browser (Client-side)

Package: launchdarkly-js-client-sdk

npm install launchdarkly-js-client-sdk

import * as ld from 'launchdarkly-js-client-sdk';

const client = ld.initialize(clientSideId, context);
await client.waitForInitialization();

// Count / occurrence metric — no context, no metricValue
client.track('signup-completed');

// Value metric
client.track('page-load-time', null, performanceMs);

// With custom data
client.track('item-added-to-cart', { itemId: 'abc123' }, itemPrice);

// Flush (useful in tests or before navigating away)
await client.flush();

---

React (Client-side)

Package: launchdarkly-react-client-sdk

npm install launchdarkly-react-client-sdk

import { useLDClient } from 'launchdarkly-react-client-sdk';

function CheckoutButton() {
  const ldClient = useLDClient();

  const handleSubmit = async () => {
    await processCheckout();

    // Count / occurrence metric
    ldClient?.track('checkout-completed');

    // Value metric
    ldClient?.track('checkout-revenue', null, orderTotal);
  };

  return <button onClick={handleSubmit}>Complete Order</button>;
}

Initialization (typically in the app root via LDProvider or asyncWithLDProvider):

import { LDProvider } from 'launchdarkly-react-client-sdk';

// Wrap your app — context is set here, not in each track() call
<LDProvider clientSideID={clientSideId} context={userContext}>
  <App />
</LDProvider>

---

Python (Server-side)

Package: launchdarkly-server-sdk

pip install launchdarkly-server-sdk

import ldclient
from ldclient.config import Config

ldclient.set_config(Config(sdk_key))
client = ldclient.get()

# Count / occurrence metric
client.track('checkout-completed', context)

# Value metric
client.track('api-response-time', context, None, response_time_ms)

# With data payload
client.track('item-purchased', context, {'item_id': 'abc123'}, purchase_amount)

# Flush
client.flush()

---

Go (Server-side)

Package: github.com/launchdarkly/go-server-sdk/v7

go get github.com/launchdarkly/go-server-sdk/v7

import (
    ld "github.com/launchdarkly/go-server-sdk/v7"
    "github.com/launchdarkly/go-server-sdk/v7/ldcontext"
)

client, _ := ld.MakeClient(sdkKey, 5*time.Second)
defer client.Close()

// Count / occurrence metric
client.TrackEvent("checkout-completed", context)

// Value metric
client.TrackMetric("api-response-time", context, responseTimeMs, nil)

// With data payload
data := ldvalue.BuildObject().Set("itemId", ldvalue.String("abc123")).Build()
client.TrackData("item-purchased", context, data)

---

Java (Server-side)

Package: com.launchdarkly:launchdarkly-java-server-sdk

<!-- Maven -->
<dependency>
  <groupId>com.launchdarkly</groupId>
  <artifactId>launchdarkly-java-server-sdk</artifactId>
  <version>7.x.x</version>
</dependency>

LDClient client = new LDClient(sdkKey);

// Count / occurrence metric
client.track("checkout-completed", context);

// Value metric
client.trackMetric("api-response-time", context, responseTimeMs);

// With data payload
LDValue data = LDValue.buildObject().put("itemId", "abc123").build();
client.trackData("item-purchased", context, data);
client.trackMetric("item-purchased", context, purchaseAmount);

// Flush
client.flush();
client.close();

---

Ruby (Server-side)

Package: launchdarkly-server-sdk

gem install launchdarkly-server-sdk

require 'ldclient-rb'

client = LaunchDarkly::LDClient.new(sdk_key)

# Count / occurrence metric
client.track('checkout-completed', context)

# Value metric
client.track('api-response-time', context, nil, response_time_ms)

# With data payload
client.track('item-purchased', context, { item_id: 'abc123' }, purchase_amount)

# Flush
client.flush

---

.NET / C# (Server-side)

Package: LaunchDarkly.ServerSdk

dotnet add package LaunchDarkly.ServerSdk

using LaunchDarkly.Sdk;
using LaunchDarkly.Sdk.Server;

var client = new LdClient(sdkKey);

// Count / occurrence metric
client.Track("checkout-completed", context);

// Value metric
client.Track("api-response-time", context, LdValue.Null, responseTimeMs);

// With data payload
var data = LdValue.BuildObject().Add("itemId", "abc123").Build();
client.Track("item-purchased", context, data, purchaseAmount);

// Flush
client.Flush();

---

iOS / Swift (Client-side)

Package: LaunchDarkly via Swift Package Manager or CocoaPods

import LaunchDarkly

// Context set during LDClient.start() — not required per track call

// Count / occurrence metric
LDClient.get()!.trackEvent(key: "checkout-completed")

// Value metric
LDClient.get()!.trackEvent(key: "api-response-time", metricValue: responseTimeMs)

// With data payload
LDClient.get()!.trackEvent(key: "item-purchased", data: ["itemId": "abc123"], metricValue: purchaseAmount)

// Flush
LDClient.get()!.flush()

---

Android / Kotlin (Client-side)

Package: com.launchdarkly:launchdarkly-android-client-sdk

// Context set during LDClient.init() — not required per track call
val client = LDClient.get()

// Count / occurrence metric
client.trackEvent("checkout-completed")

// Value metric
client.trackMetric("api-response-time", null, responseTimeMs)

// With data payload
val data = LDValue.buildObject().put("itemId", "abc123").build()
client.trackData("item-purchased", data, purchaseAmount)

// Flush
client.flush()

---

Common Wrapper Patterns

Many teams abstract LaunchDarkly calls behind a service or utility. Search for these patterns before adding a raw ldClient.track() call:

// Service wrappers
analyticsService.track('event-key');
featureFlagService.trackEvent('event-key', context);
tracking.record('event-key', metricValue);

// Module-level wrappers
import { trackEvent } from '../lib/launchdarkly';
trackEvent('event-key', context, metricValue);

// Class-based
this.ldService.track('event-key');
LDWrapper.getInstance().track('event-key');

If any of these exist, add the new call through the same wrapper — don't bypass it.

---

metricValue Quick Reference

The data parameter (before metricValue) is for arbitrary metadata — order IDs, category names, etc. It does not affect metric calculations.