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

打开 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;