发送您的第一个结构化事件

本演练将一个合成 API 结果发送到 Telemetry。目标不仅仅是收到 200 响应。首先是一个事件合约，该合约可以支持 SQL、仪表板、告警和后续调试，而无需收集原始请求负载。

开始之前

已从首页复制设置提示词？使用其中的 anon_… 密钥，即可在没有账户的情况下发送和查询事件。

如果已有账户，请在团队设置 → API 密钥中创建 read-and-write 密钥，因为下一步需要读取事件。只发送事件的应用可使用 ingest 密钥。

将密钥保存在本地环境变量或密钥管理器中：

export TELEMETRY_API_KEY="replace-with-your-key"

匿名密钥、只读密钥及读写密钥都应保密。浏览器和移动客户端记录事件时，可以使用 Ingest only 密钥；它不能查询或管理数据。这类密钥仍可能被复制并用于发送不需要的事件，请监控使用情况，并在遭到滥用时撤销。有关权限和轮换方式，请参阅 API 密钥与身份验证。

选择一个已完成的工作流程

从应用程序知道结果的边界开始。良好的首要活动包括：

• api_request_completed
• background_job_completed
• webhook_processing_completed
• checkout_completed
• agent_run_completed

更喜欢完整的结果而不是 something_happened 等通用消息。稳定的事件名称为每个生产者和查询提供相同的粒度。

对于此示例，使用合成 API 请求：

{
  "route_template": "/api/reports/:report_id",
  "method": "POST",
  "status": "success",
  "status_code": 200,
  "latency_ms": 184,
  "release": "local-demo",
  "environment": "development",
  "request_id": "req_demo_001"
}

URL 是一个路由模板，而不是包含标识符的原始 URL。该事件包括分类结果字段和安全相关标识符，但没有请求正文、授权标头、cookie 或客户内容。

使用 cURL 发送事件

curl https://api.telemetry.sh/log \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "telemetry_quickstart",
    "data": {
      "route_template": "/api/reports/:report_id",
      "method": "POST",
      "status": "success",
      "status_code": 200,
      "latency_ms": 184,
      "release": "local-demo",
      "environment": "development",
      "request_id": "req_demo_001"
    }
  }'

如果您的 SDK 或 API 版本与此示例不同，请使用 日志API 记录的确切请求形状。

从 JavaScript 发送相同的事件

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("telemetry_quickstart", {
  route_template: "/api/reports/:report_id",
  method: "POST",
  status: "success",
  status_code: 200,
  latency_ms: 184,
  release: "local-demo",
  environment: "development",
  request_id: "req_demo_001"
});

在可信服务器端代码中初始化SDK。保持跨服务的字段名称和单位一致 - 例如，始终将持续时间存储在 latency_ms 中，而不是混合秒和毫秒。

成功意味着什么

匿名查询在首个事件后可用 24 小时。请在 7 天内创建账户，以保留事件和原密钥。注册会识别当前浏览器中的试用。在其他浏览器中，先选择已有匿名 API 密钥？，粘贴密钥并点击查找我的数据，再注册。已有账户的用户可在保留我的数据中恢复密钥，然后登录。未发送事件的试用在创建 7 天后到期。

成功发送仅证明 API 接受了该事件。继续使用 验证事件摄取 检查表名称、推断类型、生成的时间戳和确切行。在第一个事件合约可查询且安全之前，不要检测更多工作流程。

这个示例是虚构数据，只用于检查 API 调用是否正常。要完成应用集成，请在一个真实流程完成时记录事件，实际运行该流程，再查询已存储的事件。仅有 telemetry_quickstart 表中的一行并不代表设置已完成。

对于更大的模式，请阅读 设计事件架构。对于敏感字段，请使用 脱敏敏感数据。