launchdarkly-metric-instrument

LaunchDarkly Metric Instrument

你正在使用一個技能，它會引導你在程式碼庫中加入 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 類型、呼叫簽章和 context 模式 — 請完全比照這些模式。

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 等
   • 找到初始化區塊，了解 client 在程式碼庫中如何被存取

3. 判斷是 client-side 還是 server-side。 這是最關鍵的區別 — 它決定了 track() 的簽章：

   SDK 類型	track() 簽章	備註
   Server-side (Node, Python, Go, Java, Ruby, .NET)	ldClient.track(eventKey, context, data?, metricValue?)	每次呼叫都需要 context
   Client-side (React, browser JS)	ldClient.track(eventKey, data?, metricValue?)	context 在初始化時設定，非每次呼叫

   請參閱 SDK Track Patterns 以取得各語言的完整範例。

步驟 2：安裝與初始化（如果 SDK 尚未存在）

如果 SDK 已存在於程式碼庫中，請跳過此步驟。

1. 從 lockfile 偵測套件管理器： 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 client。請參閱 SDK Track Patterns 以取得初始化範例。

步驟 3：找到正確的放置位置

找出使用者動作或事件發生在程式碼中的位置。

1. 如果不確定動作發生的位置，請詢問。 不要猜測放置位置 — 在錯誤位置（例如 render 方法而非 submit handler）的 track() 呼叫會產生誤導的資料。

2. 尋找正確位置的訊號：

   • 表單提交、按鈕點擊處理器、API 路由完成、mutation hooks
   • 現有的分析呼叫（segment.track()、mixpanel.track()、gtag()）— 這些通常與 LD track 呼叫應放置的位置相同
   • 註解如 // TODO: track this

3. 在撰寫任何內容之前，向使用者顯示候選位置：

   我會在這裡加入 track() 呼叫，在結帳提交處理器中 (src/checkout/CheckoutForm.tsx, 第 47 行)。
   這樣正確嗎？
   

4. 確認後再繼續（或者如果你從程式碼庫訊號中已經足夠確信）。

步驟 4：撰寫 track() 呼叫

依照步驟 1 中找到的模式撰寫呼叫。

Server-side SDK — 需要 context：

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

Client-side SDK — context 是隱含的：

ldClient.track('checkout-completed');

對於 value 指標 — 在 metricValue 中包含數值測量：

// Server-side: 延遲指標 (ms)
ldClient.track('api-response-time', context, null, responseTimeMs);

// Client-side: 營收指標
ldClient.track('purchase-completed', { orderId }, purchaseAmountUSD);

關鍵規則：

• 比對現有的 context。 不要內聯建立新的 context。找到程式碼庫中已經建立 context/user 物件的地方（用於 variation() 呼叫），並使用同一個。這是 LD 將事件關聯到正確實驗參與者的方式。
• metricValue 僅用於 value 指標。 對於 count 和 occurrence 指標，完全省略 metricValue。
• 尊重包裝模式。 如果程式碼庫將 LD 呼叫包裝在一個工具函式後面（featureFlags.track()、analytics.ldTrack()），請透過該包裝加入新的呼叫 — 而不是直接呼叫 ldClient。
• 完全比對事件金鑰。 track() 事件金鑰是區分大小寫的。請使用建立指標時使用的確切字串。

請參閱 SDK Track Patterns 以取得各語言的完整範例。

步驟 5：驗證

引導使用者在他們的本地或 staging 環境中觸發動作。 然後使用 list-metric-events 確認事件金鑰出現：

list-metric-events(projectKey, environmentKey)

如果事件金鑰出現： 確認成功並顯示摘要。

如果觸發後事件金鑰未出現， 請檢查以下清單：

問題	檢查項目
事件金鑰大小寫錯誤	track() 呼叫是否與指標的事件金鑰完全相符？
SDK 未初始化	ldClient 是否在 track() 呼叫執行前已初始化？
Server-side：context 錯誤	傳遞給 track() 的 context 是否與 variation() 呼叫使用的 context 相同？
Client-side：未先評估 flag	SDK 是否已在 track() 呼叫前初始化並識別使用者？
環境錯誤	list-metric-events 是否查詢了觸發動作用的相同環境？
資料延遲	list-metric-events 顯示最近 90 天，最多約 5 分鐘延遲 — 稍後再試一次

驗證後顯示摘要：

✓ 事件流動中：checkout-completed
  在以下環境中看到：production
  
下一步：此事件現在已準備好用於支援指標。使用 metric-create 技能來建立一個指標，
或將現有指標附加到你的實驗中。

重要背景資訊

• track() 呼叫只有在先評估 flag 時才會計入實驗。 事件會關聯到實驗參與者，因為 LD 看到了來自該 context 的 variation() 呼叫。如果使用者在未評估任何 flag 的情況下觸發動作用，事件仍可能被接收，但不會出現在實驗結果中。
• Client-side SDK 會按間隔（預設約 30 秒）或在頁面卸載時刷新事件。 在測試中，你可能需要明確呼叫 ldClient.flush() 才能立即看到事件出現。
• Server-side SDK 也會緩衝事件。 在開發環境中，在 track() 之後呼叫 ldClient.flush() 可確保事件在程序結束或測試結束前被送出。
• metricValue 的單位必須與指標定義相符。 如果指標是以單位 ms 建立的，請傳入毫秒。將秒傳入毫秒指標會產生靜默的錯誤結果。
• data 參數用於自訂中繼資料，而非指標值。 在 data 中傳入額外背景資訊（訂單 ID、類別等）。在 metricValue 中傳入數值測量。

參考資料

• SDK Track Patterns — 每個支援的 SDK 的 track() 呼叫語法、初始化和套件名稱