Rust SDK
telemetry-sh crate 提供了一個用於事件攝取和互動式查詢的小型阻塞客戶端。每種方法都會構造一個阻塞 reqwest 客戶端併傳送一個 HTTP 請求。該包不公開非同步客戶端、可設定超時、重試策略、批次處理佇列或重新整理方法。
安裝並初始化
[dependencies]
telemetry-sh = "1.0.0"
serde_json = "1.0"
uuid = { version = "1", features = ["v4"] }
use std::env;
use telemetry_sh::Telemetry;
let mut telemetry = Telemetry::new();
telemetry.init(env::var("TELEMETRY_API_KEY")?);
將金鑰保留在伺服器端設定中。將寫入範圍的金鑰用於僅攝取服務，將讀取範圍的金鑰用於報告或查詢自動化。
傳送結構化事件
use serde_json::json;
use uuid::Uuid;
let event_id = Uuid::new_v4().to_string();
let event = json!({
"event_id": event_id,
"job_name": "invoice_sync",
"status": "success",
"duration_ms": 912,
"attempt": 1,
"release": env::var("APP_RELEASE").ok(),
});
match telemetry.log("job_completed", &event) {
Ok(response) => println!("telemetry response: {response}"),
Err(error) => eprintln!(
"telemetry delivery failed event_id={} error_type=transport_error: {}",
event_id,
error
),
}
避免使用憑據、標頭、cookie、原始請求正文、提示、異常文字和私人客戶內容。更喜歡受控的類別和穩定的內部識別符號。
SDK 接受一個 serde_json::Value。陣列值可以表示 Log API 批次有效負載，但在將批次處理作為生產交付合約的一部分之前測試確切的箱子和 API 行為。
執行SQL
let query = r#"
SELECT
status,
COUNT(*) AS jobs
FROM job_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY status
ORDER BY jobs DESC
"#;
let result = telemetry.query(query)?;
let rows = result
.get("data")
.and_then(|value| value.as_array())
.cloned()
.unwrap_or_default();
println!("query rows: {}", rows.len());
結果是動態 JSON。在自動化中使用值之前驗證型別、空值、API 狀態和空結果。直接使用 非同步查詢API 進行長期執行的 JSON 或 Parquet 匯出。
阻塞和超時行為
兩種 crate 方法均使用 reqwest::blocking。在未隔離阻塞工作的情況下，請勿直接在非同步執行程式執行緒或延遲敏感的請求路徑上呼叫它們。
已發布的包不會公開其 HTTP 客戶端或設定超時。如果服務需要上下文取消、連線重用、固定超時、特定於狀態的重試或持久佇列，請改為使用應用程式擁有的 reqwest::Client 來實現記錄的 HTTP 請求。
保持傳輸策略有限，以便遙測中斷不會耗盡工作執行緒。
重試和關閉策略
僅重試暫時性連線失敗、429、502、503 和 504。使用帶有抖動的指數退避，限制總時間，並保留相同的 event_id。不要重試未更改的無效請求。
SDK 沒有要重新整理的後台佇列。成功返回 log 意味著立即請求產生了可解碼的回應；它並不是一次性儲存的承諾。在處理程序關閉之前，追蹤所需的呼叫或將持久事件保留在應用程式擁有的發件箱中。
對於普通分析，不要因為遙測不可用而將已完成的客戶操作轉變為失敗。檢視 事件傳遞和冪等性。
驗證整合
傳送已知成功和失敗的燈具，然後查詢：
SELECT timestamp_utc, event_id, job_name, status, duration_ms, error_type
FROM job_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
檢查表命名、欄位型別、單位、空行為、重複事件 ID 和敏感資料邊界。在依賴該事件發出警示之前，請先執行連線超時並正常關閉。
故障排除
- 缺少金鑰錯誤：從非空伺服器端環境值初始化客戶端。
- 執行時停頓：將阻塞呼叫移出非同步執行程式執行緒或使用應用程式擁有的非同步 HTTP 客戶端。
- 錯誤回應解碼為JSON：檢查返回的狀態和訊息；該板條箱不呼叫
error_for_status。 - 重複行：跨網路嘗試保留
event_id並監控 重複的 ID。 - 大匯出：使用HTTP非同步查詢啟動、狀態和下載流程。