Ruby HTTP 整合
使用 Ruby 標準函式庫即可呼叫 Telemetry HTTP API，無需額外的用戶端套件。應用程式自行控制逾時、重試，以及是否在傳送前持久化事件。
這些範例傳送虛構值來檢查交付。請將它們保留在預留的 telemetry_quickstart 範例資料表中；它們並未為執行中的應用程式加入事件記錄。實際使用時，在真實操作之後將觀測值記錄到該工作流程自己的資料表中，並測量操作本身的耗時，而非 Telemetry 呼叫的耗時。
設定併傳送事件
require "json"
require "net/http"
require "uri"
api_key = ENV.fetch("TELEMETRY_API_KEY")
uri = URI("https://api.telemetry.sh/log")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
table: "telemetry_quickstart",
data: {
event_id: "evt_request_101",
route_template: "/api/projects/:id",
method: "GET",
status_code: 200,
status: "success",
latency_ms: 184
}
}.to_json
response = Net::HTTP.start(
uri.hostname,
uri.port,
use_ssl: true,
open_timeout: 2,
read_timeout: 10
) { |http| http.request(request) }
unless response.is_a?(Net::HTTPSuccess)
raise "Telemetry log failed with HTTP #{response.code}"
end
Telemetry 新增 timestamp_utc。將金鑰保留在伺服器端，並且不要傳送憑據、cookie、標頭、請求參數、原始異常訊息或私人客戶內容。
傳送一批
將 data 設定為陣列：
request.body = {
table: "telemetry_quickstart",
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"
}
]
}.to_json
保持批次有界且模式相容。應用程式擁有的佇列還需要最大深度、最大壽命、溢位規則、重試預算和關閉期限。
執行SQL
使用讀取範圍的鍵：
uri = URI("https://api.telemetry.sh/query")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
query: <<~SQL
SELECT
route_template,
COUNT(*) AS requests,
ROUND(AVG(latency_ms), 0) AS avg_latency_ms
FROM telemetry_quickstart
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
AND route_template IS NOT NULL
GROUP BY route_template
ORDER BY requests DESC;
SQL
}.to_json
response = Net::HTTP.start(
uri.hostname,
uri.port,
use_ssl: true,
open_timeout: 2,
read_timeout: 30
) { |http| http.request(request) }
raise "Telemetry query failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
result = JSON.parse(response.body)
Array(result["data"]).each do |row|
# Validate expected keys and nulls before using the row.
end
使用 非同步查詢API 進行大型 JSON 或 Parquet 匯出。
重試和失敗策略
Net::OpenTimeout 表示無法建立連線。 Net::ReadTimeout 不明確，因為伺服器可能在回應丟失之前已經接受了請求。
僅重試暫時性網路故障、429、502、503 和 504。重用邏輯事件的 event_id，應用帶抖動的指數退避，並限制總執行時間。不要重試未更改的無效請求。
對於正常分析，遙測中斷不應取代完整的客戶回應。當丟失不可接受時，將計費或批准的稽核事件保留在應用程式擁有的持久發件箱中。
驗證並排除故障
傳送綜合成功和失敗事件、查詢最新行並檢查 GET /tables/<table>/schema。
KeyError：在伺服器或工作環境中設定API金鑰。401或403：更換金鑰或更正其範圍。400：檢查表命名、JSON 形狀和欄位型別相容性。- 超時：應用工作流程記錄的重試或回退策略，而不列印負載。
- 處理程序關閉：直接呼叫HTTP，沒有後台佇列需要flush；首先追蹤所需的呼叫或保留事件。