launchdarkly-metric-instrument

LaunchDarkly 指标埋点

你正在使用一项技能，它将引导你向代码库添加 track() 调用，以便 LaunchDarkly 指标可以对其进行度量。你的任务是检测正在使用的 SDK，在代码中找到合适的位置添加调用，正确编写调用，并验证事件是否已发送到 LaunchDarkly。

前提条件

此技能要求你的环境中已配置远程托管的 LaunchDarkly MCP 服务。

必需的 MCP 工具：

• list-metric-events — 埋点后验证事件是否正在流入

可选的 MCP 工具（可完善工作流）：

• get-project — 在需要初始化 SDK 时，获取正确环境的 SDK 密钥

工作流

第 1 步：检测 SDK

编写代码之前，先了解此代码库中已有的 LaunchDarkly 配置。

1. 搜索现有的 track() 调用。 这是最快的判断方式：

   • 查找 ldClient.track(、.track(、ld.track(
   • 如果已存在调用，就能立即看出 SDK 类型、调用签名和上下文模式——请完全照此采用。

2. 如果没有 track() 调用，搜索 SDK 导入和初始化代码：

   • 检查 package.json、requirements.txt、go.mod、Gemfile、*.csproj 中是否存在 LD SDK 依赖
   • 查找 LDClient、ldclient、launchdarkly-server-sdk、launchdarkly-node-server-sdk、launchdarkly-react-client-sdk 等
   • 找到初始化代码块，了解如何在整个代码库中访问客户端

3. 判断是客户端还是服务端。 这是最关键的区别，它决定了 track() 签名：

   SDK 类型	track() 签名	说明
   服务端（Node、Python、Go、Java、Ruby、.NET）	ldClient.track(eventKey, context, data?, metricValue?)	每次调用都需要上下文
   客户端（React、浏览器 JS）	ldClient.track(eventKey, data?, metricValue?)	上下文在初始化时设置，而非每次调用时设置

   请参阅 SDK Track Patterns，了解各语言的完整示例。

第 2 步：安装并初始化（如果尚未安装 SDK）

如果代码库中已经有 SDK，请跳过此步骤。

1. 根据锁文件检测包管理器：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. 使用检测到的包管理器安装相应的 SDK。请参阅 SDK Track Patterns，了解各语言对应的包名。

3. 使用 get-project 获取 SDK 密钥——获取项目，并选择用户希望埋点的环境所对应的密钥（通常用于初始测试的是 production 或 staging）。

4. 按照此代码库中已有的模式添加 SDK 初始化代码。如果有中央配置或服务层，请在那里添加 LD 客户端。初始化示例请参阅 SDK Track Patterns。

第 3 步：找到合适的位置

在代码中定位用户操作或事件发生的位置。

1. 如果不确定操作发生的位置，请先询问。 不要猜测埋点位置——在错误的位置（例如渲染方法而不是提交处理函数）调用 track() 会产生误导性数据。

2. 寻找合适位置的线索：

   • 表单提交、按钮点击处理函数、API 路由完成处、变更钩子
   • 现有分析调用（segment.track()、mixpanel.track()、gtag()）——这些调用通常与应该添加 LD track 调用的位置相同
   • 类似 // TODO: track this 的注释

3. 在编写任何内容之前，先向用户展示候选位置：

   I'll add the track() call here, in the checkout submit handler (src/checkout/CheckoutForm.tsx, line 47).
   Does that look right?
   

4. 确认后再继续（如果你根据代码库中的线索足够确定，也可以直接继续）。

步骤 4：编写 track() 调用

按照步骤 1 中的模式编写调用。

服务端 SDK — 必须提供上下文：

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

客户端 SDK — 上下文是隐式的：

ldClient.track('checkout-completed');

对于 value 指标 — 添加包含数值测量值的 metricValue：

// Server-side: latency metric (ms)
ldClient.track('api-response-time', context, null, responseTimeMs);

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

关键规则：

• 匹配现有上下文。 不要在内联代码中构建新上下文。找到代码库中构建上下文/用户对象的位置（variation() 调用会使用该对象），并使用同一个对象。这样 LD 才能将事件关联到正确的实验参与者。
• 仅对 value 指标使用 metricValue。 对于 count 和 occurrence 指标，完全省略 metricValue。
• 遵循封装模式。 如果代码库通过工具函数封装了 LD 调用（featureFlags.track()、analytics.ldTrack()），请通过该封装添加新的调用，而不是直接调用 ldClient。
• 确保事件键完全匹配。 track() 事件键区分大小写。请使用创建指标时所用的确切字符串。

完整的各语言示例请参阅 SDK Track 模式。

步骤 5：验证

引导用户在本地或预发布环境中触发该操作。然后使用 list-metric-events 确认事件键已出现：

list-metric-events(projectKey, environmentKey)

如果事件键已出现： 确认成功并展示摘要。

如果触发后事件键仍未出现，请逐项检查以下内容：

问题	检查项
事件键大小写错误	track() 调用中的事件键是否与指标的事件键完全匹配？
SDK 未初始化	track() 调用运行前是否已初始化 ldClient？
服务端：上下文错误	传给 track() 的上下文是否与 variation() 调用使用的上下文相同？
客户端：尚未评估标志	调用 track() 前，SDK 是否已初始化并识别用户？
环境错误	list-metric-events 查询的环境是否与触发操作的环境相同？
数据延迟	list-metric-events 显示最近 90 天的数据，最多可能延迟约 5 分钟 — 请稍后重试

验证完成后，展示摘要：

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

重要上下文

• 只有先评估标志，track() 调用才会计入实验。 LD 会看到该上下文发起的 variation() 调用，因此事件会关联到实验参与者。如果用户触发操作时未评估任何标志，事件仍可能被接收，但不会出现在实验结果中。
• 客户端 SDK 会按间隔刷新事件（默认约 30 秒），或在页面卸载时刷新。在测试中，可能需要显式调用 ldClient.flush()，才能立即看到事件出现。
• 服务端 SDK 也会缓冲事件。 在开发过程中，于 track() 后调用 ldClient.flush()，可确保在进程退出或测试结束前发送事件。
• metricValue 的单位必须与指标定义一致。 如果创建指标时使用的单位是 ms，请传入毫秒值。将秒值传给单位为毫秒的指标会导致结果悄然出错。
• data 参数用于自定义元数据，而非指标值。 请将额外上下文（订单 ID、类别等）放入 data。将数值测量值放入 metricValue。

参考资料

• SDK Track 模式 — 所有受支持 SDK 的 track() 调用语法、初始化方式和包名称