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가 추가되었습니다. 자격 증명, 인증 헤더, 쿠키, 요청 입력, 예외 텍스트 또는 개인 고객 콘텐츠를 보내지 마세요. 수집에는 쓰기 범위 키를 사용합니다.
일괄 보내기
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.
}
대규모 JSON 또는 Parquet 내보내기에는 비동기 쿼리 API를 사용하세요.
재시도 및 실패 정책
시간 초과는 모호합니다. 응답이 손실되기 전에 서버가 이벤트를 수락했을 수 있습니다. 일시적인 연결 실패(429, 502, 503 및 504)만 재시도합니다. event_id를 재사용하고, 지터가 있는 백오프를 적용하고, 캡 시도를 시도합니다. 변경되지 않은 400를 다시 시도하지 마십시오.
일반적인 분석의 경우 원격 분석 실패가 완료된 고객 응답을 대체해서는 안 됩니다. 삭제할 수 없는 청구 또는 승인된 감사 이벤트에 대해 애플리케이션 소유의 내구성 있는 발신함을 사용하십시오.
확인 및 문제 해결
최신 행을 쿼리하고 GET /tables/<table>/schema를 통해 스키마를 검사합니다. 성공, 실패, 재시도 및 시간 초과 분기를 실행합니다.
- 빈 API 키: 요청을 구성하기 전에 서버 측 구성을 확인합니다.
curl_exec는false를 반환합니다. 키나 페이로드가 아닌curl_errno및 제어된 오류 범주를 기록합니다.401또는403: 키를 교체하거나 범위를 수정하세요.400: 테이블 이름 지정, JSON 모양 및 유형 호환성을 검사합니다.- 프로세스 종료: 직접 HTTP 호출에는 플러시할 백그라운드 큐가 없습니다. 필요한 요청을 추적하거나 이벤트를 먼저 유지하세요.
Laravel 통합, 로그 API, 속도 제한 및 배칭 가이드를 참조하세요.