讓程式設計代理使用這篇文件

開啟 Claude Code、Codex、Cursor 或其他編碼代理的集中提示包，然後將其適應此處介紹的工作流程。

開啟提示詞包連線真實遙測

本頁內容

安裝並初始化
傳送一個結構化事件
傳送一批
執行鍵入的查詢
交付行為和重試
驗證整合
故障排除

JavaScript 和 TypeScript SDK

在伺服器端JavaScript或TypeScript中使用telemetry-sh包。當前客戶端透過 ESM 和 CommonJS 建置公開即時 log 和 query 呼叫。它不維護後台事件佇列或公開重新整理方法。

不要在瀏覽器程式碼中初始化包：Telemetry API 金鑰授予對團隊的存取權限，並且不得在客戶端捆綁包中提供。

安裝並初始化

npm install telemetry-sh

ES模組：

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

通用JS：

const telemetry = require("telemetry-sh");

telemetry.init(process.env.TELEMETRY_API_KEY);

在伺服器或worker啟動期間呼叫init一次。將寫入範圍的金鑰用於僅攝取程式碼，使用讀取範圍的金鑰進行報告或僅查詢自動化。

傳送一個結構化事件

當應用程式需要觀察交付成功或失敗時，等待返回的 Promise：

const eventId = crypto.randomUUID();

try {
  await telemetry.log("api_request_completed", {
    event_id: eventId,
    route_template: "/api/projects/:id",
    method: "POST",
    status_code: 201,
    status: "success",
    latency_ms: 184,
    environment: process.env.APP_ENV,
    release: process.env.APP_RELEASE,
  });
} catch (error) {
  console.error("Telemetry delivery failed", {
    event_id: eventId,
    error_type: "telemetry_delivery_failed",
  });
}

將原始 URL、請求正文、cookie、授權標頭、秘密、提示和私人客戶內容保留在有效負載之外。使用穩定的路由範本、內部識別符號和受控錯誤類別。

傳送一批

log 接受相容物件的陣列。批次處理可減少請求開銷，但會增加受一個失敗請求影響的事件數量。

await telemetry.log("job_completed", [
  {
    event_id: "evt_job_101",
    job_name: "invoice_sync",
    status: "success",
    duration_ms: 912,
  },
  {
    event_id: "evt_job_102",
    job_name: "invoice_sync",
    status: "failed",
    duration_ms: 2401,
    error_type: "provider_timeout",
  },
]);

JavaScript 客戶端立即傳送提供的陣列。它不會將呼叫收集到內部批次中。如果應用程式引入了自己的緩衝區，請按照配料和背壓中所述限制其大小、期限、重試預算和關閉行為。

執行鍵入的查詢

type ReliabilityRow = {
  requests: number;
  route_template: string;
};

const result = await telemetry.query<ReliabilityRow>(`
  SELECT
    route_template,
    COUNT(*) AS requests
  FROM api_request_completed
  WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  GROUP BY route_template
  ORDER BY requests DESC
`);

for (const row of result.data) {
  console.log(row.route_template, row.requests);
}

通用型別描述 TypeScript 的結果行；它不會在執行時驗證 SQL 結果。在自動化中使用查詢之前檢查空結果和意外空值。

SDK 的 query 方法呼叫互動式查詢端點。對非同步 JSON 或 Parquet 匯出使用記錄的 HTTP 流，而不是假設 SDK 選項建立並輪詢非同步作業。

交付行為和重試

當前包對每個 log 或 query 呼叫執行一個 fetch 請求。它不會新增 SDK 超時、自動重試、持久佇列或重新整理生命週期。

如果重試攝取：

僅重試暫時傳輸故障 429、502、503 和 504。
重用邏輯事件的event_id。
應用帶有抖動的指數退避。
嘗試次數上限和經過時間。
除非遙測明確屬於該工作流程的永續性合約的一部分，否則不要將已完成的客戶操作轉變為失敗。

使用應用程式擁有的持久發件箱來進行無法刪除的計費或批准的審查事件。參見事件傳遞和冪等性。

驗證整合

傳送綜合成功和失敗事件後，執行：

SELECT
  timestamp_utc,
  event_id,
  route_template,
  status,
  latency_ms,
  error_type
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;