콘텐츠로 건너뛰기
Telemetry
문서 찾아보기
SDK업데이트된 2026년 7월 29일Telemetry 편집 및 제품 팀의 검토3 최소 읽기

코딩 에이전트와 함께 이 문서를 사용하세요.

Claude Code, Codex, Cursor 또는 다른 코딩 에이전트에 대한 집중 프롬프트 팩을 연 다음 여기에서 다루는 워크플로에 맞게 조정하세요.

이 페이지에서
  1. 이벤트 구성 및 보내기
  2. 일괄 보내기
  3. 쿼리 실행
  4. 재시도 및 실패 정책
  5. 확인 및 문제 해결

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, 503504)만 재시도합니다. event_id를 재사용하고, 지터가 있는 백오프를 적용하고, 캡 시도를 시도합니다. 변경되지 않은 400를 다시 시도하지 마십시오.

일반적인 분석의 경우 원격 분석 실패가 완료된 고객 응답을 대체해서는 안 됩니다. 삭제할 수 없는 청구 또는 승인된 감사 이벤트에 대해 애플리케이션 소유의 내구성 있는 발신함을 사용하십시오.

확인 및 문제 해결

최신 행을 쿼리하고 GET /tables/<table>/schema를 통해 스키마를 검사합니다. 성공, 실패, 재시도 및 시간 초과 분기를 실행합니다.

  • 빈 API 키: 요청을 구성하기 전에 서버 측 구성을 확인합니다.
  • curl_execfalse를 반환합니다. 키나 페이로드가 아닌 curl_errno 및 제어된 오류 범주를 기록합니다.
  • 401 또는 403: 키를 교체하거나 범위를 수정하세요.
  • 400: 테이블 이름 지정, JSON 모양 및 유형 호환성을 검사합니다.
  • 프로세스 종료: 직접 HTTP 호출에는 플러시할 백그라운드 큐가 없습니다. 필요한 요청을 추적하거나 이벤트를 먼저 유지하세요.

Laravel 통합, 로그 API, 속도 제한배칭 가이드를 참조하세요.

관련 제품 기능

안정적인 이벤트 이름, 타입이 지정된 필드, 개인 정보 보호 검토 컨텍스트를 캡처합니다.

소유권 및 기술 참조

이 설명은 Telemetry 편집팀의 소유입니다. 제품 팀은 동작, 예시, 경계를 검토합니다.

편집 기준 검토