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, 503 및 504만 재시도하세요. 논리적 이벤트의 event_id를 재사용하고, 지터가 포함된 지수 백오프를 적용하고, 총 경과 시간을 제한합니다. 변경되지 않은 잘못된 요청을 재시도하지 마세요.
일반적인 분석의 경우 텔레메트리 중단이 완료된 고객 응답을 대체해서는 안 됩니다. 손실이 허용되지 않는 경우 애플리케이션 소유의 내구성 있는 발신함에서 청구 또는 승인된 감사 이벤트를 지속합니다.
확인 및 문제 해결
합성 성공 및 실패 이벤트를 보내고, 최신 행을 쿼리하고, GET /tables/<table>/schema를 검사합니다.
KeyError: 서버 또는 작업자 환경에서 API 키를 구성합니다.401또는403: 키를 교체하거나 범위를 수정하세요.400: 테이블 이름 지정, JSON 모양 및 필드 유형 호환성을 검사합니다.- 시간 초과: 페이로드를 인쇄하지 않고 워크플로의 문서화된 재시도 또는 대체 정책을 적용합니다.
- 프로세스 종료: 직접 HTTP 호출에는 플러시할 백그라운드 큐가 없습니다. 필요한 호출을 추적하거나 이벤트를 먼저 유지하세요.
Rails 통합, 로그 API, 이벤트 전달 가이드 및 수집 문제 해결을 참조하세요.