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. 在编写任何内容之前向用户显示候选位置：

   我将在此处添加 track() 调用，在结账提交处理程序中（src/checkout/CheckoutForm.tsx，第 47 行）。
   看起来对吗？
   

4. 确认后继续（或者如果您从代码库信号中足够确信）。

步骤 4：编写 track() 调用

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

服务端 SDK — 需要上下文：

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

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

ldClient.track('checkout-completed');

对于 value 指标 — 包含带有数值测量的 metricValue：

// 服务端：延迟指标（毫秒）
ldClient.track('api-response-time', context, null, responseTimeMs);

// 客户端：收入指标
ldClient.track('purchase-completed', { orderId }, purchaseAmountUSD);

关键规则：

• 匹配现有上下文。 不要内联构造新上下文。找到代码库已经构建其上下文/用户对象（用于 variation() 调用）的位置，并使用相同的对象。这是 LD 将事件关联到正确实验参与者的方式。
• metricValue 仅用于 value 指标。 对于 count 和 occurrence 指标，完全省略 metricValue。
• 尊重包装器模式。 如果代码库将 LD 调用包装在实用程序后面（featureFlags.track()、analytics.ldTrack()），请通过该包装器添加新调用 — 而不是直接调用 ldClient。
• 精确匹配事件键。 track() 事件键区分大小写。使用创建指标时使用的确切字符串。

有关每种语言的完整示例，请参阅 SDK Track Patterns。

步骤 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 分钟 — 稍后再试

验证后显示摘要：

✓ 事件正在流动：checkout-completed
  在以下环境中看到：production
  
下一步：此事件现在可以用于支持指标。使用 metric-create 技能设置一个指标，
或将现有指标附加到您的实验中。

重要上下文

• track() 调用仅在首先评估标志时才计入实验。 事件与实验参与者相关联，因为 LD 看到了来自该上下文的 variation() 调用。如果用户在没有评估任何标志的情况下触发操作，事件可能仍会被摄取，但不会出现在实验结果中。
• 客户端 SDK 按间隔刷新事件（默认约 30 秒）或在页面卸载时刷新。在测试中，您可能需要显式调用 ldClient.flush() 以立即看到事件。
• 服务端 SDK 也会缓冲事件。 在开发中，在 track() 之后调用 ldClient.flush() 可确保在进程退出或测试结束之前发送事件。
• metricValue 单位必须与指标定义匹配。 如果指标创建时使用单位 ms，则传递毫秒。将秒传递给毫秒指标会产生静默错误的结果。
• data 参数用于自定义元数据，而不是指标值。 在 data 中传递额外上下文（订单 ID、类别等）。在 metricValue 中传递数值测量。

参考

• SDK Track Patterns — 每个支持的 SDK 的 track() 调用语法、初始化和包名称