launchdarkly-metric-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LaunchDarkly Metric Create

LaunchDarkly 指标创建

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.

你正在使用的技能将引导你完成 LaunchDarkly 指标的创建流程。对于自定义指标来说，首先要保障事件上报通路畅通，再创建指标。你的任务是确定合适的指标类型，如果事件尚未上报则先完成埋点（包括 SDK 配置和环境变量配置），检查是否有重复指标，给出指标配置建议，获得用户明确确认后，再创建并验证指标。

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)

本技能需要你在环境中配置远程托管的 LaunchDarkly MCP 服务器。

必需的 MCP 工具：

```
create-metric
```
— 创建指标
```
get-metric
```
— 创建后验证指标
```
get-environment
```
— 埋点时拉取客户端 SDK 密钥

可选的 MCP 工具（优化工作流）：

```
list-metrics
```
— 检查是否存在使用相同事件 key 的现有指标，了解命名规范
```
list-metric-events
```
— 确定自定义指标的事件 key 前，查询哪些事件 key 近期有上报数据

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:

	What it is	How the user refers to it	What you do with it
LaunchDarkly project	The project inside the user's LD account where the metric will be created	Usually sounds like an environment or team name: `my-app` , `anthony-agent-dev-5000` , `production`	Pass as `projectKey` to all MCP tool calls
Local codebase	The developer's application on disk that you'll instrument with a `track()` call	Often a folder name, repo name, or app name: `checkout_proj` , `frontend` , `my-react-app`	Use to find and edit source files

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.

用户会接触到两类完全独立、但都被叫做「项目」的对象，你必须时刻明确区分二者：

	定义	用户的常用表述	你的处理方式
LaunchDarkly 项目	用户 LD 账号内用于存放指标的项目	通常类似环境或团队名称： `my-app` 、 `anthony-agent-dev-5000` 、 `production`	所有 MCP 工具调用时传入作为 `projectKey` 参数
本地代码库	存储在磁盘上、你需要添加 `track()` 调用埋点的开发者应用	通常是文件夹名、仓库名或应用名： `checkout_proj` 、 `frontend` 、 `my-react-app`	用于查找和编辑源代码文件

从用户输入中区分二者的规则：

如果用户说 「我存在X路径的应用」 或 「我的代码库」 或 「我的仓库」 → 指的是本地代码库，
```
X
```
是文件夹路径或项目名称，不是 LaunchDarkly key。
如果用户说 「添加到X里」 或 「在LaunchDarkly里」 或 「我的LD项目」 → 指的是LaunchDarkly项目，
```
X
```
是API调用使用的
```
projectKey
```
。
用户完全可以把本地代码库命名为
```
checkout_proj
```
，同时把 LaunchDarkly 项目命名为
```
anthony-agent-dev-5000
```
，二者没有关联。
永远不要默认本地代码库名称就是 LaunchDarkly 项目 key。 如果不确定二者的区别，直接询问：「请确认一下你的 LaunchDarkly 项目 key 是什么？（它和你的本地应用名称不同，你可以在 LD 控制台的账户设置 > 项目中找到它。）」

如果两类项目都需要用到（比如需要埋点的自定义指标），请在继续操作前分别明确确认二者的值。

Workflow

工作流

Step 1: Determine the Metric Kind

步骤1：确定指标类型

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

Kind	How events are collected	Requires
`custom`	Developer calls `ldClient.track(eventKey)` in code	`eventKey`
`pageview`	Fires automatically when a user visits a matching URL — no SDK call needed	`urls` (URL match rules)
`click`	Fires automatically when a user clicks a CSS selector on a matching URL — no SDK call needed	`urls` + `selector`

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

click

would work, suggest it over

custom

— it requires no code changes.

LaunchDarkly 有三类指标，请先选择合适的类型再进行后续操作。

类型	事件采集方式	所需参数
`custom`	开发者在代码中调用 `ldClient.track(eventKey)`	`eventKey`
`pageview`	用户访问匹配的URL时自动触发 —— 无需额外SDK调用	`urls` （URL匹配规则）
`click`	用户点击匹配URL页面上的指定CSS选择器元素时自动触发 —— 无需额外SDK调用	`urls` + `selector`

选择规则：

用户说「追踪用户访问页面/访问URL的行为」→ pageview
（优先选择，无需埋点）
用户说「追踪用户点击按钮/链接的行为」→ click
用户说「追踪自定义事件」或提及
```
track()
```
调用 → custom

如果

pageview

或

click

可以满足需求，优先推荐使用这两类指标，不需要修改代码。

Step 2: Resolve the Data Source

步骤2：确定数据源

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.

针对
pageview
和
click
指标：

询问用户需要匹配的URL，确认URL匹配规则的类型：
- ```
substring
```
  — URL包含指定字符串（最常用）
- ```
exact
```
  — URL必须完全匹配
- ```
canonical
```
  — 匹配规范URL
- ```
regex
```
  — 完整正则匹配
针对
```
click
```
指标，还需要询问CSS选择器（例如
```
.checkout-btn
```
、
```
#submit
```
）。
不需要调用
```
list-metric-events
```
—— 这两类指标不使用事件 key。
直接跳转到步骤3。

针对
custom
指标 —— 先检查事件上报情况，必要时先埋点：

立即调用

list-metric-events

查看哪些事件 key 已经在正常上报：

list-metric-events(projectKey, environmentKey?)

情况A —— 事件 key 已经在返回列表中： 和用户确认该key无误后跳转到步骤3，不需要额外埋点。

情况B —— 事件 key 不在返回列表中： 没有事件上报的指标无法统计任何数据，创建指标前必须先完成事件埋点。 不要只是警告用户询问是否继续，默认将埋点作为下一步操作。

按照下面的埋点子流程完成操作，然后重新调用

list-metric-events

确认事件已经正常上报，再跳转到步骤3。只有当用户明确表示要先创建指标后续再补埋点时，可以跳过埋点流程，此时需要在最后提醒用户，事件完成埋点上报前指标不会产生任何数据。

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

步骤2b：事件埋点（事件未上报时执行）

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:

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,
  },
})

Omit the

options

block entirely if they are on

app.launchdarkly.com

— the defaults are correct and no extra config is needed.

5. Install and initialize the SDK if it isn't already present. Check

package.json

(or the equivalent dependency file) for an existing LD SDK. If none is found, install the right one for the project's stack:

React →
```
launchdarkly-react-client-sdk
```
Browser JS →
```
launchdarkly-js-client-sdk
```
Node.js server →
```
@launchdarkly/node-server-sdk
```

Initialize the SDK at the app's entry point (e.g. wrap the React root with

LDProvider

, configure

LDClient.init()

in the server entry, etc.). Pass the client-side ID from the env file. Use an anonymous user/context as the default unless the app already manages user context.

6. Add the
track()
call. In the location identified in step 1, add the call immediately before or after the action completes:

Count / occurrence metric:
```
ldClient.track('event-key')
```

Value metric:

ldClient.track('event-key', null, numericValue)

Use optional chaining (

ldClient?.track(...)

) in client-side code where the client may not yet be initialized.

7. Verify events are flowing. After the instrumentation changes are made, remind the user to run the app and trigger the event at least once. Then call

list-metric-events

again to confirm the key appears before proceeding to metric creation.

本子流程会在代码库中添加

track()

调用，并将应用连接到对应的 LaunchDarkly 环境。完成所有步骤后再回到主流程。

1. 找到代码库中合适的埋点位置。 找到事件自然触发的函数或处理逻辑（例如结账提交处理逻辑、表单提交回调）。修改代码前先阅读相关源代码，理解现有代码结构。

2. 确定事件 key。 如果用户没有指定，建议使用描述性的kebab-case格式key，和代码实现的功能对应（例如

checkout-completed

、

signup-submitted

）。使用前先和用户确认。

3. 拉取客户端SDK密钥。 询问用户要连接的环境名称（例如「test」、「production」、「staging」），然后调用：

get-environment(projectKey, environmentKey)

使用返回结果中的

clientSideId

字段。

4. 写入环境变量文件。 检查是否已经存在

.env

文件（或等价文件，如

.env.local

、

.env.development

等）。

如果文件不存在，创建新文件。
如果文件存在且已经包含对应key（例如
```
VITE_LD_CLIENT_SIDE_ID
```
），将存储的值和
```
get-environment
```
返回的
```
clientSideId
```
对比。如果值不一致，告知用户差异：
「你的
```
.env
```
文件中已经配置了
```
VITE_LD_CLIENT_SIDE_ID=<旧值>
```
，但
```
get-environment
```
接口返回的
```
<env>
```
环境对应值为
```
<新值>
```
，是否需要更新？」不要静默保留旧值 —— 客户端ID不匹配会导致事件上报到错误的项目或环境。
如果文件存在但没有对应key，添加该key，不要修改其他值。

使用和项目构建工具匹配的变量名（例如 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

或控制台URL判断 —— 如果地址的host不是

app.launchdarkly.com

，说明是非生产部署。不确定时直接询问：

「你连接的是 app.launchdarkly.com 还是其他 LaunchDarkly 实例？（例如内部环境或测试环境）」

如果用户使用非标准host，在

.env

文件中添加三个额外变量：

VITE_LD_BASE_URL=https://<用户的host>
VITE_LD_STREAM_URL=https://clientstream.<用户的host域名>
VITE_LD_EVENTS_URL=https://events.<用户的host域名>

并在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。如果没有找到，安装和项目技术栈匹配的SDK：

React →
```
launchdarkly-react-client-sdk
```
浏览器JS →
```
launchdarkly-js-client-sdk
```
Node.js 服务端 →
```
@launchdarkly/node-server-sdk
```

在应用入口点初始化SDK（例如用

LDProvider

包裹 React 根组件，在服务端入口配置

LDClient.init()

等）。传入环境变量中的客户端ID，默认使用匿名用户/上下文，除非应用已经有现成的用户上下文管理逻辑。

6. 添加
track()
调用。在步骤1确定的位置，在动作完成的前后添加调用：

计数/发生次数指标：
```
ldClient.track('event-key')
```

数值指标：

ldClient.track('event-key', null, numericValue)

在客户端代码中使用可选链语法（

ldClient?.track(...)

），避免客户端未初始化时报错。

7. 验证事件上报正常。 完成埋点修改后，提醒用户运行应用并至少触发一次事件，然后再次调用

list-metric-events

确认事件key出现在列表中，再继续创建指标。

Step 3: Check for Existing Metrics

步骤3：检查现有指标

Before creating anything, use

list-metrics

to scan the project:

Check for duplicates. Search for metrics with the same event key, URL pattern, or similar names. Avoid creating a second metric that measures the same thing — instead, flag the existing metric and ask the user if they want to reuse it.
Learn the naming convention. Are metric keys
```
kebab-case
```
or
```
snake_case
```
? Are there common tag patterns? Match what already exists.
Understand the tag taxonomy. Tags like
```
team:growth
```
,
```
area:checkout
```
, or
```
type:guardrail
```
may already exist. Suggest relevant tags based on what the user describes.

创建指标前，调用

list-metrics

扫描项目：

检查重复指标。 查找使用相同事件key、URL规则或名称相似的指标，避免创建重复衡量同一维度的第二个指标 —— 如果有现有匹配指标，告知用户并询问是否要复用。
了解命名规范。 现有指标key是
```
kebab-case
```
还是
```
snake_case
```
？是否有通用的标签规则？匹配现有规范。
了解标签体系。 可能已经存在
```
team:growth
```
、
```
area:checkout
```
、
```
type:guardrail
```
这类标签，根据用户描述的场景推荐相关标签。

Step 4: Propose the Metric Configuration

步骤4：给出指标配置建议

Before calling any API, surface a proposed configuration in plain language for the user to confirm or edit.

Determine measure type. The right choice depends on what the user is trying to learn and how they'll use the metric — in an experiment, a guarded rollout, or a release policy. Do not assume. When the event is something a user can do repeatedly (click, add to cart, view page, etc.), always ask before proposing:

"Are you trying to measure how many times this event happens in total (
count
), or what percentage of users triggered it at least once (
occurrence
)?"

Tie the question to their context:

Experiments — occurrence is common for conversion goals (did the treatment cause more users to do X?); count is better for engagement or volume goals (did the treatment cause more total actions?)
Guarded rollouts / release policies — occurrence is typical for error rate guardrails (what fraction of users hit an error?); count suits absolute volume guardrails (total error events)
If the user explicitly says "percent of users" or "conversion rate" →
```
occurrence
```
If the user explicitly says "number of times" or "total events" →
```
count
```

Only skip asking if the intent is unambiguous from context (e.g. "API latency" →

value

, "error rate" →

count

, "signup conversion" →

occurrence

What the user wants to measure	Measure type	Means
Total times the event occurred	`count`	Raw event count per analysis unit
Whether each user triggered the event at all	`occurrence`	Conversion / binary (did it happen?)
A numeric value attached to the event	`value`	Latency, revenue, score, etc.

Determine success criteria:

Higher is better →
```
HigherThanBaseline
```
(conversion rate, revenue, engagement)
Lower is better →
```
LowerThanBaseline
```
(latency, error rate, bounce rate)

Use common templates as defaults when the user's intent is clear:

User intent	kind	measure type	success criteria	unit
Page visit / view rate	`pageview`	`occurrence`	`HigherThanBaseline`	—
Button / link click rate	`click`	`occurrence`	`HigherThanBaseline`	—
API latency / page load time	`custom`	`value` (average)	`LowerThanBaseline`	`ms`
Signup / conversion rate	`custom`	`occurrence`	`HigherThanBaseline`	—
Error count / rate	`custom`	`count`	`LowerThanBaseline`	—
Revenue per user	`custom`	`value` (sum)	`HigherThanBaseline`	`USD`

Present the proposed config before creating — don't silently fire the 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?

STOP HERE. Do not call any API. Do not proceed to Step 5. Wait for the user to explicitly confirm before doing anything else. The user must respond with an approval (e.g. "yes", "looks good", "proceed") before you call

create-metric

. If there is any ambiguity in the proposed config — such as a choice between

sum

average

, or the event key name — ask that question as part of the proposal and wait for the answer before continuing.

调用任何API前，用通俗易懂的语言给出建议的配置，供用户确认或修改。

确定统计类型。 正确的选择取决于用户的使用目的和指标用途：用于实验、灰度防护、还是发布策略。不要默认猜测。 如果事件是用户可以重复触发的（点击、加购、页面浏览等），建议前先询问：

「你需要统计的是事件累计发生的总次数（
count
），还是触发过该事件的用户占比（
occurrence
）？」

结合用户的场景提问：

实验场景 —— 转化目标通常用
```
occurrence
```
（实验组是否带来了更多完成X的用户？）；参与度或总量目标用
```
count
```
更合适（实验组是否带来了更多总操作？）
灰度防护/发布策略场景 —— 错误率防护通常用
```
occurrence
```
（遇到错误的用户占比？）；绝对量防护用
```
count
```
更合适（总错误事件数）
如果用户明确说「用户占比」或「转化率」 →
```
occurrence
```
如果用户明确说「次数」或「总事件量」 →
```
count
```

只有当上下文意图非常明确时可以跳过询问（例如「API延迟」→

value

、「错误率」→

count

、「注册转化率」→

occurrence

）。

用户想要统计的内容	统计类型	含义
事件累计发生次数	`count`	每个分析单元的原始事件计数
每个用户是否至少触发过一次事件	`occurrence`	转化率/二元结果（是否发生？）
事件附带的数值	`value`	延迟、收入、分数等

确定成功判断标准：

数值越高越好 →
```
HigherThanBaseline
```
（转化率、收入、参与度）
数值越低越好 →
```
LowerThanBaseline
```
（延迟、错误率、跳出率）

用户意图明确时使用通用模板作为默认值：

用户意图	类型	统计类型	成功判断标准	单位
页面访问/浏览率	`pageview`	`occurrence`	`HigherThanBaseline`	—
按钮/链接点击率	`click`	`occurrence`	`HigherThanBaseline`	—
API延迟/页面加载时间	`custom`	`value` （平均值）	`LowerThanBaseline`	`ms`
注册/转化率	`custom`	`occurrence`	`HigherThanBaseline`	—
错误计数/错误率	`custom`	`count`	`LowerThanBaseline`	—
每用户收入	`custom`	`value` （总和）	`HigherThanBaseline`	`USD`

创建前先展示建议的配置 —— 不要静默调用API：

建议配置的指标：
  Key:              checkout-page-viewed
  名称:             Checkout Page Viewed
  类型:             pageview（访问URL时自动触发 —— 无需修改代码）
  URL规则:          包含子串 "/checkout"
  统计类型:         occurrence（统计访问过该页面的用户占比）
  成功判断标准:     HigherThanBaseline

是否继续，还是需要调整配置？

在此处暂停。 不要调用任何API，不要进入步骤5。等待用户明确确认后再继续操作。用户必须给出明确同意（例如「是的」、「没问题」、「继续」）才能调用

create-metric

。如果建议的配置有模糊的地方 —— 比如选择

sum

还是

average

，或者事件key的名称 —— 在给出建议时同时提问，等待用户回复后再继续。

Step 5: Create the Metric

步骤5：创建指标

Only proceed once the user has explicitly confirmed the proposed config in Step 4. If you have not yet received a confirmation, go back and wait.

Once the user confirms, call

create-metric

. The tool handles the translation from

measureType

to the underlying API fields — you never need to pass

isNumeric

unitAggregationType

directly.

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?
)

只有用户在步骤4明确确认建议的配置后才能继续。 如果还没收到确认，返回上一步等待。

用户确认后，调用

create-metric

。工具会自动将

measureType

转换为底层API所需的字段 —— 你不需要直接传入

isNumeric

或

unitAggregationType

。

create-metric(
  projectKey,
  key,
  name,
  kind,              // "custom" | "pageview" | "click"
  eventKey?,         // 仅kind="custom"时需要
  urls?,             // 仅kind="pageview"或"click"时需要: [{ kind, url }]
  selector?,         // 仅kind="click"时需要: CSS选择器字符串
  measureType,       // "count" | "occurrence" | "value"
  successCriteria,   // "HigherThanBaseline" | "LowerThanBaseline"
  valueAggregation?, // 仅measureType="value"时需要: "average"（默认）或 "sum"
  unit?,             // 展示标签: "ms", "USD" 等
  description?,
  tags?
)

Step 6: Verify

步骤6：验证

Use

get-metric

to confirm the metric was created with the right configuration:

Key and name match what was requested.
kind is correct —
```
custom
```
,
```
pageview
```
, or
```
click
```
.
measureType is correct — double-check by reading back the
```
measureType
```
field, not just
```
isNumeric
```
.
eventKey / urls / selector are set to the intended values.
successCriteria is correct.

Surface a summary to the user:

✓ 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}

The

create-metric

tool returns a

_links.ui

field with the correct URL for the environment being used. Always use that value — never hard-code

app.launchdarkly.com

调用

get-metric

确认指标创建的配置正确：

Key和名称和请求的一致。
类型正确 ——
```
custom
```
、
```
pageview
```
或
```
click
```
。
统计类型正确 —— 核对
```
measureType
```
字段，不要只看
```
isNumeric
```
。
eventKey / urls / selector 设置为预期值。
成功判断标准正确。

给用户展示创建结果摘要：

✓ 指标已创建: checkout-page-viewed
  类型:     pageview（访问URL时自动追踪）
  URL规则:  包含子串 "/checkout"
  统计维度: occurrence（转化率）
  目标:     越高越好

在 LaunchDarkly 中查看: {create-metric 返回的 _links.ui 字段}

create-metric

工具返回的

_links.ui

字段包含对应环境的正确访问URL，始终使用该值 —— 不要硬编码

app.launchdarkly.com

。

Measure Type Reference

统计类型参考

The

create-metric

tool translates

measureType

to the LD API fields internally. You never need to set

isNumeric

unitAggregationType

directly.

measureType	isNumeric	unitAggregationType	Use for
`count`	false	sum	Raw event counts — error rate, click count
`occurrence`	false	average	Conversion — did the user do the thing?
`value` (average)	true	average	Per-user mean — average latency, average session length
`value` (sum)	true	sum	Per-user total — total revenue, total items purchased

For

value

metrics,

valueAggregation

defaults to

"average"

. Pass

valueAggregation: "sum"

for revenue or cumulative totals.

create-metric

工具内部会自动将

measureType

转换为 LD API 所需的字段，你不需要直接设置

isNumeric

或

unitAggregationType

。

measureType	isNumeric	unitAggregationType	适用场景
`count`	false	sum	原始事件计数 —— 错误率、点击量
`occurrence`	false	average	转化率 —— 用户是否完成了目标动作？
`value` （平均值）	true	average	每用户均值 —— 平均延迟、平均会话时长
`value` （总和）	true	sum	每用户累计值 —— 总收入、总购买商品数

对于

value

类型指标，

valueAggregation

默认值为

"average"

，统计收入或累计总量时传入

valueAggregation: "sum"

。

Important Context

重要说明

Prefer
pageview
and
click
over
custom
when possible. They require no SDK instrumentation and work automatically in browser environments.
Event keys are case-sensitive.
```
checkout-completed
```
and
```
Checkout-Completed
```
are different events. Match the key exactly as it appears in your
```
track()
```
calls.
Custom metrics without events produce no data. A custom metric is only useful once its event key is actively being tracked in production (or the relevant environment). If you created the metric before instrumenting the event, remind the user.
Metric keys are immutable. Once created, a metric's key cannot be changed. Choose carefully.
Metrics are project-scoped. A metric created in one project is not visible in another. Make sure
```
projectKey
```
matches where the experiment or flag lives.
One primary metric per experiment. When attaching this metric to an experiment, clarify whether it's the primary metric (the one that determines success or failure) or a secondary metric (a guardrail or supporting signal). See the LaunchDarkly docs for experiment setup.

优先使用
pageview
和
click
类型，而非
custom
。不需要SDK埋点，在浏览器环境中自动生效。
事件key区分大小写。
```
checkout-completed
```
和
```
Checkout-Completed
```
是不同的事件，必须和
```
track()
```
调用中的key完全匹配。
没有事件上报的自定义指标不会产生任何数据。 只有当事件key在生产（或对应环境）中正常上报后，自定义指标才会生效。如果先创建了指标再补埋点，记得提醒用户。
指标key不可修改。 创建后指标的key无法变更，请谨慎选择。
指标是项目级别的。 在一个项目中创建的指标在其他项目中不可见，确保
```
projectKey
```
和实验或开关所在的项目匹配。
每个实验一个核心指标。 将指标关联到实验时，明确它是核心指标（决定实验成败）还是次要指标（防护指标或辅助参考信号）。实验配置详情参考 LaunchDarkly 文档。