Go SDK
使用 telemetry-go 进行来自 Go 服务的直接同步事件和查询调用。已发布的客户端为每个方法调用创建一个 HTTP 请求。它不公开上下文、自定义 http.Client、SDK 超时、自动重试、批处理或刷新队列。
安装并初始化
go get github.com/telemetry-sh/telemetry-go
import (
"os"
telemetry "github.com/telemetry-sh/telemetry-go"
)
telemetryClient := telemetry.NewTelemetry()
telemetryClient.Init(os.Getenv("TELEMETRY_API_KEY"))
在应用程序启动期间初始化一个客户端。使用写入范围的密钥进行摄取，使用读取范围的密钥进行仅查询自动化。
发送结构化事件
event := map[string]interface{}{
"event_id": eventID,
"route_template": "/api/projects/:id",
"method": "POST",
"status_code": 201,
"status": "success",
"latency_ms": float64(time.Since(startedAt).Microseconds()) / 1000,
"request_id": requestID,
"release": os.Getenv("APP_RELEASE"),
}
response, err := telemetryClient.Log("api_request_completed", event)
if err != nil {
log.Printf("telemetry delivery failed event_id=%s error_type=transport_error", eventID)
}
_ = response
请勿发送包含标识符、标头、cookie、请求正文、凭据或私人客户内容的原始请求路径。使用标准化的路由模式和受控的错误类别。
Go SDK 每次 Log 调用接受一个 map[string]interface{}。如果应用程序拥有的工作线程需要批量摄取，请直接使用 HTTP 日志 API。
运行查询
query := `
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
`
result, err := telemetryClient.Query(query)
if err != nil {
return fmt.Errorf("query telemetry: %w", err)
}
rows, _ := result["data"].([]interface{})
fmt.Printf("rows=%d\n", len(rows))
响应使用通用映射和切片。在自动化中使用值之前，请检查类型、缺失字段、API 状态和空结果。使用 异步查询API 进行大型 JSON 或 Parquet 导出。
生产运输边界
当前的SDK构造http.Client{}没有超时。因此，停滞的网络请求可能会超出 HTTP 处理程序或工作线程的延迟预算。当需要有界超时、上下文取消、连接池配置、批量负载或显式状态处理时，请将 Telemetry HTTP 合约包装在服务的现有 http.Client 中。
保持相同的事件架构和授权规则：
client := &http.Client{Timeout: 2 * time.Second}
将该客户端用于 POST https://api.telemetry.sh/log，其 JSON 主体包含 table 和 data。在解码响应之前检查 HTTP 状态。
重试和关键路径策略
仅重试暂时性连接失败、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;
确认表名、字段类型、单位以及是否存在敏感内容。在将仪器连接到高流量处理程序之前测试进程关闭和停止的 Telemetry 请求。
故障排除
- 初始化错误：在第一次方法调用之前确认服务器端密钥非空。
- 请求挂起：通过具有超时和请求上下文的客户端使用 HTTP API。
- 不成功响应显示为数据：检查返回的状态字段；当前的 SDK 解码 JSON 主体，而不强制 HTTP 成功。
- 架构拒绝：保持字段类型稳定并删除空或不受支持的形状。
- 重试后重复行：保留
event_id并使用 重复的事件配方 进行审核。
继续使用 Go HTTP 服务器结构化日志记录、日志API 和 速率限制和 API 错误。