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 錯誤。