cURL 和 HTTP API 示例
使用 cURL 验证 API 密钥、重现 SDK 请求、自动化服务器端脚本或在向应用程序添加检测之前测试故障处理。
配置密钥
在不记录秘密值的 shell 中导出密钥：
export TELEMETRY_API_KEY="YOUR_API_KEY"
使用写入范围的密钥进行摄取，使用单独的读取范围的密钥进行查询或报告。禁用围绕扩展密钥的命令的 shell 跟踪。
发送一个事件
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
--request POST \
"https://api.telemetry.sh/log" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"table": "api_request_completed",
"data": {
"event_id": "evt_request_101",
"route_template": "/api/projects/:id",
"method": "GET",
"status_code": 200,
"status": "success",
"latency_ms": 184
}
}
JSON
Telemetry 添加 timestamp_utc。请勿将 API 密钥、授权标头、cookie、原始请求正文、提示或私人客户内容作为事件字段发送。
发送兼容批次
data 字段可以是一个数组：
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
--request POST \
"https://api.telemetry.sh/log" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"table": "job_completed",
"data": [
{
"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"
}
]
}
JSON
保持每个对象与相同的表模式兼容。批处理可减少请求开销，但会增加受一个失败请求影响的事件数量。
运行SQL
curl --fail-with-body \
--connect-timeout 2 \
--max-time 30 \
--request POST \
"https://api.telemetry.sh/query" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"query": "SELECT route_template, COUNT(*) AS requests, ROUND(AVG(latency_ms), 0) AS avg_latency_ms FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '24 hours' GROUP BY route_template ORDER BY requests DESC;"
}
JSON
检查 status、data 和 key_order 字段，而不是假设结果非空。
导出更大的结果
启动异步 Parquet 导出：
curl --fail-with-body \
--connect-timeout 2 \
--max-time 30 \
--request POST \
"https://api.telemetry.sh/query/async" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"query": "SELECT * FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '30 days' ORDER BY timestamp_utc DESC;",
"format": "parquet"
}
JSON
使用相同的授权标头轮询返回的 status_url。当query_status为completed时，下载download_url。停止对 failed 进行轮询并强制执行总体截止日期。
检查并验证表
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
"https://api.telemetry.sh/tables/api_request_completed/schema" \
--header "Authorization: ${TELEMETRY_API_KEY}"
发送综合的成功、失败、重试和超时情况。在创建仪表板或告警之前，请确认字段类型、单位、UTC 时间戳以及是否缺少敏感字段。
重试和退出代码策略
--fail-with-body 对于 HTTP 故障退出非零，同时保留响应正文以进行安全诊断。
- 退出
6：DNS解析失败。 - 退出
7：连接失败。 28：超时退出；服务器可能已接受也可能未接受该请求。- HTTP
400：修复请求；不要重试不变。 - HTTP
401或403：替换凭证或更正其范围。 - HTTP
429、502、503或504：使用有界指数退避和抖动重试。
将相同的 event_id 重复用于逻辑事件。在未考虑重复交付的情况下，请勿使用 --retry-all-errors。