JavaScript 和 TypeScript SDK

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

以下範例在伺服器端初始化套件。不要將匿名試用、read 或 read-and-write 金鑰放入瀏覽器程式碼。只傳送事件的用戶端可以使用 Ingest only（僅攝取） 金鑰；請在將其放入公開版本前確認權限。在儀表板中查看結果，或在可信的伺服器上使用另一把讀取金鑰。詳見 API 金鑰與身分驗證。

以下傳送範例使用虛構值檢查 SDK 的資料傳送。請保留在 telemetry_quickstart 資料表中；這些範例不能證明應用程式已完成埋點。實際使用時，應在選定的應用程式操作完成後記錄觀測到的值，並使用自己的工作流程資料表。

安裝並初始化

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("telemetry_quickstart", {
    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("telemetry_quickstart", [
  {
    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 telemetry_quickstart
  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 本身沒有逾時設定、自動重試、持久佇列或 flush 機制。

如果重試攝取：

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

對於不能遺失的計費事件或已獲准記錄的稽核事件，請使用由應用程式管理的持久傳送佇列。參見事件傳遞和冪等性。

驗證整合

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

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

確認資料表名稱、欄位型別、空行為、UTC 時間戳以及不存在敏感欄位。然後在建立儀表板或警示之前測試重試、超時和關閉分支。

故障排除

API key is not initialized：在第一個 SDK 方法之前呼叫 telemetry.init。
401：替換丟失、無效或已撤銷的金鑰。
403：使用具有所需範圍的金鑰。
400：檢查表名、JSON形狀、欄位型別相容性；不要重試不變。
429 或 5xx：如果可以安全地多次傳遞事件，則使用有界重試策略。
程序在傳送完成前結束：追蹤並等待各次呼叫，或在關閉前持久保存必要事件；SDK 沒有待傳送事件的 flush 佇列。

繼續使用日誌API、速率限制和 API 錯誤和 Node.js 和 Express 整合。

Next.js App Router 範例

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