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

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

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

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

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

Ruby HTTP 통합

Ruby 표준 라이브러리로 Telemetry HTTP API를 호출할 수 있습니다. 별도의 클라이언트 패키지가 필요하지 않습니다. 애플리케이션이 시간 제한, 재시도, 전송 전 이벤트 저장 여부를 결정합니다.

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

이벤트 구성 및 보내기

require "json"
require "net/http"
require "uri"

api_key = ENV.fetch("TELEMETRY_API_KEY")
uri = URI("https://api.telemetry.sh/log")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
  table: "telemetry_quickstart",
  data: {
    event_id: "evt_request_101",
    route_template: "/api/projects/:id",
    method: "GET",
    status_code: 200,
    status: "success",
    latency_ms: 184
  }
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true,
  open_timeout: 2,
  read_timeout: 10
) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "Telemetry log failed with HTTP #{response.code}"
end

Telemetry에 timestamp_utc가 추가되었습니다. 키를 서버 측에 유지하고 자격 증명, 쿠키, 헤더, 요청 매개 변수, 원시 예외 메시지 또는 개인 고객 콘텐츠를 보내지 마십시오.

일괄 보내기

data를 어레이로 설정합니다.

request.body = {
  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"
    }
  ]
}.to_json

일괄 처리를 제한적이고 스키마와 호환되게 유지하세요. 애플리케이션 소유 대기열에는 최대 깊이, 최대 수명, 오버플로 규칙, 재시도 예산 및 종료 기한도 필요합니다.

SQL 실행

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

uri = URI("https://api.telemetry.sh/query")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
  query: <<~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
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true,
  open_timeout: 2,
  read_timeout: 30
) { |http| http.request(request) }

raise "Telemetry query failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)

result = JSON.parse(response.body)
Array(result["data"]).each do |row|
  # Validate expected keys and nulls before using the row.
end

대규모 JSON 또는 Parquet 내보내기에는 비동기 쿼리 API를 사용하세요.

재시도 및 실패 정책

Net::OpenTimeout는 연결을 설정할 수 없음을 의미합니다. Net::ReadTimeout는 응답이 손실되기 전에 서버가 요청을 수락했을 수 있으므로 모호합니다.

일시적인 네트워크 오류인 429, 502, 503 및 504만 재시도하세요. 논리적 이벤트의 event_id를 재사용하고, 지터가 포함된 지수 백오프를 적용하고, 총 경과 시간을 제한합니다. 변경되지 않은 잘못된 요청을 재시도하지 마세요.

일반적인 분석의 경우 텔레메트리 중단이 완료된 고객 응답을 대체해서는 안 됩니다. 손실이 허용되지 않는 경우 애플리케이션 소유의 내구성 있는 발신함에서 청구 또는 승인된 감사 이벤트를 지속합니다.

확인 및 문제 해결

합성 성공 및 실패 이벤트를 보내고, 최신 행을 쿼리하고, GET /tables/<table>/schema를 검사합니다.

  • KeyError: 서버 또는 작업자 환경에서 API 키를 구성합니다.
  • 401 또는 403: 키를 교체하거나 범위를 수정하세요.
  • 400: 테이블 이름 지정, JSON 모양 및 필드 유형 호환성을 검사합니다.
  • 시간 초과: 페이로드를 인쇄하지 않고 워크플로의 문서화된 재시도 또는 대체 정책을 적용합니다.
  • 프로세스 종료: 직접 HTTP 호출에는 플러시할 백그라운드 큐가 없습니다. 필요한 호출을 추적하거나 이벤트를 먼저 유지하세요.

Rails 통합, 로그 API, 이벤트 전달 가이드 및 수집 문제 해결을 참조하세요.

관련 기능

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

페이지 작성자 및 참고 자료

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

문서 검토 방법