发送您的第一个结构化事件
本演练将一个合成 API 结果发送到 Telemetry。目标不仅仅是收到 200 响应。首先是一个事件合约，该合约可以支持 SQL、仪表板、告警和后续调试，而无需收集原始请求负载。
开始之前
在 团队设置 → API 密钥 中创建一个团队和一个 write 范围的密钥。将值保存在本地环境变量或秘密管理器中：
export TELEMETRY_API_KEY="replace-with-your-key"
请勿在浏览器 JavaScript、移动应用程序、公共存储库或屏幕截图中公开团队密钥。有关范围和旋转指南，请参阅 API 密钥与身份验证。
选择一个已完成的工作流程
从应用程序知道结果的边界开始。良好的首要活动包括：
api_request_completedbackground_job_completedwebhook_processing_completedcheckout_completedagent_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": "api_request_completed",
"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("api_request_completed", {
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 中，而不是混合秒和毫秒。
成功意味着什么
成功发送仅证明 API 接受了该事件。继续使用 验证事件摄取 检查表名称、推断类型、生成的时间戳和确切行。在第一个事件合约可查询且安全之前，不要检测更多工作流程。