Rust SDK
telemetry-sh 크레이트는 이벤트 수집 및 대화형 쿼리를 위한 소형 차단 클라이언트를 제공합니다. 각 메서드는 차단 reqwest 클라이언트를 구성하고 하나의 HTTP 요청을 보냅니다. 크레이트는 비동기 클라이언트, 구성 가능한 시간 초과, 재시도 정책, 일괄 대기열 또는 플러시 방법을 노출하지 않습니다.
설치 및 초기화
[dependencies]
telemetry-sh = "1.0.0"
serde_json = "1.0"
uuid = { version = "1", features = ["v4"] }
use std::env;
use telemetry_sh::Telemetry;
let mut telemetry = Telemetry::new();
telemetry.init(env::var("TELEMETRY_API_KEY")?);
서버측 구성에 키를 보관하세요. 수집 전용 서비스에는 쓰기 범위 키를 사용하고 보고서 또는 쿼리 자동화에는 읽기 범위 키를 사용하세요.
구조화된 이벤트 보내기
use serde_json::json;
use uuid::Uuid;
let event_id = Uuid::new_v4().to_string();
let event = json!({
"event_id": event_id,
"job_name": "invoice_sync",
"status": "success",
"duration_ms": 912,
"attempt": 1,
"release": env::var("APP_RELEASE").ok(),
});
match telemetry.log("job_completed", &event) {
Ok(response) => println!("telemetry response: {response}"),
Err(error) => eprintln!(
"telemetry delivery failed event_id={} error_type=transport_error: {}",
event_id,
error
),
}
자격 증명, 헤더, 쿠키, 원시 요청 본문, 프롬프트, 예외 텍스트 및 개인 고객 콘텐츠를 피하세요. 통제된 카테고리와 안정적인 내부 식별자를 선호합니다.
SDK는 하나의 serde_json::Value를 수용합니다. 배열 값은 로그 API 대량 페이로드를 나타낼 수 있지만 프로덕션 납품 계약의 일괄 처리 부분을 만들기 전에 정확한 상자 및 API 동작을 테스트합니다.
SQL 실행
let query = r#"
SELECT
status,
COUNT(*) AS jobs
FROM job_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY status
ORDER BY jobs DESC
"#;
let result = telemetry.query(query)?;
let rows = result
.get("data")
.and_then(|value| value.as_array())
.cloned()
.unwrap_or_default();
println!("query rows: {}", rows.len());
결과는 동적 JSON입니다. 자동화에서 값을 사용하기 전에 유형, null, API 상태 및 빈 결과의 유효성을 검사하십시오. 장기 실행 JSON 또는 Parquet 내보내기에는 비동기 쿼리 API를 직접 사용하세요.
차단 및 시간 초과 동작
두 상자 방법 모두 reqwest::blocking를 사용합니다. 차단 작업을 분리하지 않고 비동기 실행기 스레드나 대기 시간에 민감한 요청 경로에서 직접 호출하지 마세요.
게시된 크레이트는 HTTP 클라이언트를 노출하거나 시간 초과를 구성하지 않습니다. 서비스에 컨텍스트 취소, 연결 재사용, 고정된 시간 초과, 상태별 재시도 또는 지속성 대기열이 필요한 경우 대신 애플리케이션 소유 reqwest::Client를 사용하여 문서화된 HTTP 요청을 구현하세요.
원격 분석 중단으로 인해 작업자 스레드가 소진되지 않도록 전송 정책을 제한적으로 유지하세요.
재시도 및 종료 정책
일시적인 연결 실패(429, 502, 503 및 504)만 재시도합니다. 지터와 함께 지수 백오프를 사용하고 총 시간을 제한하며 동일한 event_id를 유지합니다. 변경되지 않은 잘못된 요청을 재시도하지 마세요.
SDK에는 플러시할 백그라운드 대기열이 없습니다. 성공적인 log 반환은 즉각적인 요청이 디코딩 가능한 응답을 생성했음을 의미합니다. 정확히 한 번만 저장하겠다는 약속은 아닙니다. 프로세스 종료 전에 필요한 호출을 추적하거나 애플리케이션 소유의 아웃박스에서 지속성 이벤트를 유지합니다.
일반적인 분석의 경우 텔레메트리을 사용할 수 없기 때문에 완료된 고객 작업을 실패로 전환하지 마십시오. 이벤트 전달 및 멱등성을 검토하세요.
통합 확인
알려진 성공 및 실패 픽스처를 보낸 후 다음을 쿼리합니다.
SELECT timestamp_utc, event_id, job_name, status, duration_ms, error_type
FROM job_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
테이블 이름 지정, 필드 유형, 단위, Null 동작, 중복 이벤트 ID 및 민감한 데이터 경계를 확인하세요. 알림 이벤트에 의존하기 전에 연결 시간 초과 및 정상적인 종료를 실행하십시오.
문제 해결
- 키 누락 오류: 비어 있지 않은 서버 측 환경 값에서 클라이언트를 초기화합니다.
- 런타임 중단: 비동기 실행기 스레드에서 차단 호출을 이동하거나 애플리케이션 소유 비동기 HTTP 클라이언트를 사용합니다.
- 오류 응답은 JSON로 디코딩됩니다. 반환된 상태와 메시지를 검사합니다. 상자는
error_for_status를 호출하지 않습니다. - 중복 행: 네트워크 시도 전반에 걸쳐
event_id를 보존하고 중복 ID를 모니터링합니다. - 대규모 내보내기: HTTP 비동기 쿼리 시작, 상태 및 다운로드 흐름을 사용합니다.
로그 API, 수집 문제 해결 및 프로덕션 계측 체크리스트를 계속 진행하세요.