자바 HTTP 통합

Telemetry는 기본 Java SDK를 게시하지 않습니다. Java 또는 JVM 서비스에 구조화된 이벤트 수집 또는 SQL 쿼리가 필요한 경우 하나의 애플리케이션 소유 java.net.http.HttpClient를 통해 HTTP API를 사용하세요.

이 경계는 서비스 제어 하에 연결 재사용, 시간 초과, 재시도, 직렬화 및 실패 정책을 유지합니다.

하나의 공유 클라이언트 만들기

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

HttpClient telemetryHttp = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(2))
    .build();

애플리케이션 시작 중에 클라이언트를 한 번 생성합니다. 수집에는 서버 측 쓰기 범위 API 키를 사용하고 보고서 또는 쿼리 자동화에는 별도의 읽기 범위 키를 사용하세요.

하나의 구조화된 이벤트 보내기

애플리케이션에서 이미 승인한 JSON 라이브러리를 사용하세요. 이 예에서는 eventJson가 요청 본문에서 조립되지 않고 허용 목록에 있는 객체에서 직렬화되었다고 가정합니다.

String eventJson = objectMapper.writeValueAsString(Map.of(
    "table", "api_request_completed",
    "data", Map.of(
        "event_id", eventId,
        "route_template", "/api/projects/:id",
        "method", "POST",
        "status_code", 201,
        "status", "success",
        "latency_ms", latencyMs,
        "request_id", requestId,
        "release", release
    )
));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telemetry.sh/log"))
    .timeout(Duration.ofSeconds(3))
    .header("Authorization", telemetryApiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(eventJson))
    .build();

HttpResponse<String> response = telemetryHttp.send(
    request,
    HttpResponse.BodyHandlers.ofString()
);

if (response.statusCode() < 200 || response.statusCode() >= 300) {
    recordDeliveryFailure(response.statusCode(), eventId);
}

경로 템플릿과 제어된 오류 범주를 사용합니다. 헤더, 쿠키, 자격 증명, 요청 본문, SQL 매개변수, 스택 추적, 프롬프트, 생성된 콘텐츠 또는 무제한 예외 메시지를 직렬화하지 마세요.

SQL 실행

읽기 범위 키를 사용하여 query를 포함하는 JSON 본체를 https://api.telemetry.sh/query에 게시합니다.

String queryJson = objectMapper.writeValueAsString(Map.of(
    "query", """
        SELECT route_template, COUNT(*) AS requests
        FROM api_request_completed
        WHERE timestamp_utc >= now() - INTERVAL '24 hours'
        GROUP BY route_template
        ORDER BY requests DESC
        """
));

HttpRequest queryRequest = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telemetry.sh/query"))
    .timeout(Duration.ofSeconds(15))
    .header("Authorization", telemetryReadApiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(queryJson))
    .build();

HTTP 상태와 응답 status, data 및 key_order 필드를 확인하세요. 빈 결과를 구문 분석 실패가 아닌 유효한 상태로 처리합니다.

실패 및 재시도 정책

연결 오류, 429, 502, 503 및 504와 같은 제한된 일시적 오류만 재시도합니다. 지터와 함께 지수 백오프를 사용하고 경과 시간을 제한하며 시도 전반에 걸쳐 동일한 event_id를 유지합니다. 400, 401 또는 403 응답을 변경하지 않고 재시도하지 마세요.

일반 제품 분석의 경우 텔레메트리 실패가 완료된 고객 응답을 대체해서는 안 됩니다. 청구 또는 승인된 감사 이벤트가 지속 가능해야 하는 경우 비즈니스 상태와 동일한 트랜잭션에 보낸 편지함 기록을 작성하고 이를 작업자에게 전달합니다.

통합 확인

제어된 성공, 실패, 재시도 및 시간 초과 픽스처를 보낸 다음 최근 행을 검사합니다.

SELECT timestamp_utc, event_id, route_template, status, latency_ms, error_type
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;

이벤트 그레인, 테이블 이름, 필드 유형, 단위, UTC 시간, 개인정보 보호 경계를 확인하세요. 트래픽이 많은 경로에 배송하기 전에 Telemetry 시간 초과 및 프로세스 종료를 테스트하세요.

Spring Boot 통합, 로그 API, 속도 제한 및 오류 및 이벤트 전달 및 멱등성을 계속 진행하세요.