OpenAPI 사양
Telemetry는 문서화된 HTTP API에 대해 기계 판독 가능한 OpenAPI 3.1 사양을 게시합니다. 이를 사용하여 엔드포인트 계약을 검사하고, 입력된 클라이언트를 시작점으로 생성하고, API 탐색기를 구성하거나 CI에서 예제 요청을 검증합니다.
사양에는 다음이 포함됩니다.
POST /log를 사용한 구조화된 이벤트 수집;POST /query를 갖춘 동기식 SQL;- 비동기식 JSON 및 Parquet는
POST /query/async및GET /query/async/{job_id}로 내보냅니다. - 테이블 목록, 스키마 검사, 보존, 파티션 열 및 삭제;
- 대시보드 목록 작성, 생성, 교체 업데이트 및 삭제
- 알림 목록, 생성, 부분 업데이트 및 삭제
- 더 이상 사용되지 않는 것으로 표시된 레거시 행 삭제 엔드포인트입니다.
사양 다운로드
curl -fsS https://telemetry.sh/openapi.json -o telemetry-openapi.json
이 문서는 https://api.telemetry.sh를 서버로 사용하고 지원되는 인증 헤더 형식을 모두 설명합니다.
Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
저장소에 커밋된 사양, 소스 제어, 생성된 문서, 예제, 로그 또는 클라이언트 구성에 실제 API 키를 넣지 마십시오.
문서 유효성 검사
OpenAPI 3.1 호환 유효성 검사기를 사용하세요. 예를 들어 로컬에 설치된 Redocly CLI의 경우:
npx @redocly/cli lint telemetry-openapi.json
도구 업그레이드로 인해 릴리스 동작이 예기치 않게 변경되지 않도록 CI에 유효성 검사기 버전을 고정하세요. 모호한 스키마에 대한 알림을 자동으로 억제하지 않고 검토 항목으로 처리합니다.
신중하게 클라이언트 생성
생성된 클라이언트는 엔드포인트 가이드를 대체하는 것이 아니라 스캐폴딩입니다. 프로덕션 사용 전:
- 인증 및 API 키 범위를 확인합니다.
- 연결 및 응답 시간 초과를 구성합니다.
- 제한된 지수 백오프 및 지터가 있는 일시적인 실패만 재시도합니다.
- 수집을 재시도할 때 이벤트 식별자를 보존합니다.
- 비동기 쿼리 작업에 총 폴링 기한을 적용합니다.
- 텔레메트리 오류로 인해 애플리케이션 작업자가 지치지 않도록 합니다.
- 파괴적인 테이블과 행 삭제 방법을 별도로 검토하세요.
OpenAPI 스키마는 해당 필드가 이벤트 계약 및 SQL 프로젝션에 따라 달라지기 때문에 의도적으로 유연한 이벤트 페이로드 및 쿼리 결과 행을 개방형으로 둡니다. 하나의 전역 이벤트 형태를 가정하는 대신 애플리케이션에서 해당 페이로드에 대한 도메인 유형을 생성합니다.
진실의 근원 경계
사양은 이 저장소의 공개 API 문서를 미러링합니다. 사람이 읽을 수 있는 페이지는 운영 지침, 정규화 동작, 예제 및 오류 모드의 소스로 남아 있습니다.
계획별 할당량은 변경될 수 있으며 사양에서 글로벌 수치 비율로 인코딩되지 않습니다. 현재 계정 한도는 제품 및 결제 설정을 확인하세요. OpenAPI 문서와 라이브 API 응답이 일치하지 않는 경우 최소한의 안전한 복제물을 캡처하여 [email protected]에 보고하세요. 자격 증명이나 개인 페이로드를 기록하여 불일치를 해결하지 마십시오.