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 超时、自动重试、持久队列或刷新生命周期。

如果重试摄取：

仅重试暂时传输故障 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 刷新队列。

继续使用日志API、速率限制和 API 错误和 Node.js 和 Express 集成。

Next.js App Router 示例

让编程智能体使用这篇文档