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

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

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

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

Ruby HTTP 통합

Telemetry의 HTTP API는 Ruby의 표준 라이브러리와 함께 작동합니다. 이는 시간 제한, 재시도 및 내구성 정책을 애플리케이션 제어에 맡기면서 종속성 표면을 작게 유지합니다.

이벤트 구성 및 보내기

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: "api_request_completed",
  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: "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"
    }
  ]
}.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 api_request_completed
    WHERE timestamp_utc >= now() - INTERVAL '24 hours'
    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, 503504만 재시도하세요. 논리적 이벤트의 event_id를 재사용하고, 지터가 포함된 지수 백오프를 적용하고, 총 경과 시간을 제한합니다. 변경되지 않은 잘못된 요청을 재시도하지 마세요.

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

확인 및 문제 해결

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

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

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

관련 제품 기능

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

소유권 및 기술 참조

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

편집 기준 검토