콘텐츠로 건너뛰기
Telemetry
문서 찾아보기

SDK업데이트된 2026년 10월 1일3 최소 읽기

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

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

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

PHP HTTP 통합

PHP의 cURL 확장은 추가 클라이언트 패키지 없이 Telemetry HTTP API를 호출할 수 있습니다. 서버 측 구성에서 API 키를 유지하고 명시적인 연결 및 요청 시간 초과를 사용하십시오.

이 예제는 전달을 확인하기 위해 가상의 값을 보냅니다. 예약된 샘플 테이블 telemetry_quickstart에 보관하세요. 실행 중인 애플리케이션을 계측하는 예제가 아닙니다. 실제 사용에서는 실제 작업 후 관측값을 해당 워크플로 전용 테이블에 기록하고 Telemetry 호출이 아닌 작업 자체의 소요 시간을 측정하세요.

이벤트 구성 및 보내기

<?php

$apiKey = getenv("TELEMETRY_API_KEY");
if (!is_string($apiKey) || $apiKey === "") {
    throw new RuntimeException("TELEMETRY_API_KEY is not configured");
}

$payload = [
    "table" => "telemetry_quickstart",
    "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" => "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",
        ],
    ],
];

일괄 처리를 제한적이고 스키마와 호환되도록 유지합니다. 애플리케이션이 이벤트를 대기열에 추가하는 경우 최대 깊이, 최대 수명, 오버플로 동작, 재시도 예산 및 종료 처리를 정의합니다.

쿼리 실행

읽기 범위 키를 사용합니다.

<?php

$sql = <<<'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;

$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, 속도 제한 및 배칭 가이드를 참조하세요.

관련 기능

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

페이지 작성자 및 참고 자료

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

문서 검토 방법