PHP HTTP 整合
PHP的cURL分機可以呼叫Telemetry HTTP API，無需額外的客戶端包。將 API 金鑰保留在伺服器端設定中，並使用顯式連線和請求超時。
設定併傳送事件
<?php
$apiKey = getenv("TELEMETRY_API_KEY");
if (!is_string($apiKey) || $apiKey === "") {
throw new RuntimeException("TELEMETRY_API_KEY is not configured");
}
$payload = [
"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,
],
];
$request = curl_init("https://api.telemetry.sh/log");
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT_MS => 2_000,
CURLOPT_TIMEOUT_MS => 10_000,
CURLOPT_HTTPHEADER => [
"Authorization: " . $apiKey,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$curlError = curl_error($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
if ($body === false || $status < 200 || $status >= 300) {
throw new RuntimeException(
"Telemetry log failed with HTTP " . $status .
($curlError !== "" ? " and a transport error" : "")
);
}
$response = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
Telemetry 新增 timestamp_utc。請勿傳送憑據、授權標頭、cookie、請求輸入、異常文字或私人客戶內容。使用寫入範圍的金鑰進行攝取。
傳送一批
data 值可能是相容行的陣列：
$payload = [
"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",
],
],
];
保持批次有界且架構相容。如果應用程式對事件進行排隊，請定義最大深度、最大期限、溢位行為、重試預算和關閉處理。
執行查詢
使用讀取範圍的鍵：
<?php
$sql = <<<'SQL'
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;
SQL;
$request = curl_init("https://api.telemetry.sh/query");
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT_MS => 2_000,
CURLOPT_TIMEOUT_MS => 30_000,
CURLOPT_HTTPHEADER => [
"Authorization: " . $apiKey,
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["query" => $sql], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
if ($body === false || $status < 200 || $status >= 300) {
throw new RuntimeException("Telemetry query failed with HTTP " . $status);
}
$results = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
foreach ($results["data"] ?? [] as $row) {
// Validate expected keys and nulls before using the row.
}
使用 非同步查詢API 進行大型 JSON 或 Parquet 匯出。
重試和失敗策略
超時是不明確的：伺服器可能在回應丟失之前已經接受了事件。僅重試暫時性連線失敗、429、502、503 和 504。重複使用 event_id，應用帶抖動的退避，並限制嘗試。請勿重試未更改的 400。
對於普通分析，遙測失敗不應取代完整的客戶回應。使用應用程式擁有的持久發件箱來進行無法刪除的計費或批准的審查事件。
驗證並排除故障
透過 GET /tables/<table>/schema 查詢最新行並檢查架構。練習成功、失敗、重試和超時分支。
- 空 API 金鑰：在構造請求之前驗證伺服器端設定。
curl_exec返回false：記錄curl_errno和受控錯誤類別，而不是金鑰或負載。401或403：更換金鑰或更正其範圍。400：檢查表命名、JSON 形狀和型別相容性。- 處理程序關閉：直接呼叫HTTP，沒有後台佇列需要flush；首先追蹤所需的請求或持久化事件。
請參閱 Laravel 整合、日誌API、速率限制 和 配料指南。