cURL 및 HTTP API 예
애플리케이션에 계측을 추가하기 전에 cURL을 사용하여 API 키를 확인하고, SDK 요청을 재현하고, 서버 측 스크립트를 자동화하거나, 실패 처리를 테스트하세요.
키 구성
비밀 값을 기록하지 않는 셸에서 키를 내보냅니다.
export TELEMETRY_API_KEY="YOUR_API_KEY"
수집에는 쓰기 범위 키를 사용하고 쿼리나 보고서에는 별도의 읽기 범위 키를 사용하세요. 키를 확장하는 명령에 대한 쉘 추적을 비활성화합니다.
이벤트 하나 보내기
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
--request POST \
"https://api.telemetry.sh/log" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"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
}
}
JSON
Telemetry에 timestamp_utc가 추가되었습니다. API 키, 인증 헤더, 쿠키, 원시 요청 본문, 프롬프트 또는 개인 고객 콘텐츠를 이벤트 필드로 보내지 마세요.
호환되는 배치 보내기
data 필드는 배열일 수 있습니다.
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
--request POST \
"https://api.telemetry.sh/log" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"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"
}
]
}
JSON
모든 객체가 동일한 테이블 스키마와 호환되도록 유지하세요. 일괄 처리는 요청 오버헤드를 줄이지만 하나의 실패한 요청으로 인해 영향을 받는 이벤트 수를 늘립니다.
SQL 실행
curl --fail-with-body \
--connect-timeout 2 \
--max-time 30 \
--request POST \
"https://api.telemetry.sh/query" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"query": "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;"
}
JSON
비어 있지 않은 결과를 가정하는 대신 status, data 및 key_order 필드를 확인하세요.
더 큰 결과 내보내기
비동기 Parquet 내보내기를 시작합니다.
curl --fail-with-body \
--connect-timeout 2 \
--max-time 30 \
--request POST \
"https://api.telemetry.sh/query/async" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"query": "SELECT * FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '30 days' ORDER BY timestamp_utc DESC;",
"format": "parquet"
}
JSON
동일한 인증 헤더를 사용하여 반환된 status_url를 폴링합니다. query_status가 completed인 경우 download_url를 다운로드합니다. failed에서 폴링을 중지하고 전체 기한을 시행합니다.
테이블 검사 및 확인
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
"https://api.telemetry.sh/tables/api_request_completed/schema" \
--header "Authorization: ${TELEMETRY_API_KEY}"
합성 성공, 실패, 재시도 및 시간 초과 사례를 보냅니다. 대시보드나 알림을 생성하기 전에 필드 유형, 단위, UTC 타임스탬프 및 민감한 필드가 없는지 확인하세요.
재시도 및 종료 코드 정책
--fail-with-body는 안전한 진단을 위해 응답 본문을 유지하면서 HTTP 오류에 대해 0이 아닌 값을 종료합니다.
6종료: DNS 확인에 실패했습니다.7종료: 연결에 실패했습니다.28종료: 시간 초과; 서버가 요청을 수락했을 수도 있고 수락하지 않았을 수도 있습니다.- HTTP
400: 요청을 수정합니다. 변경하지 않고 다시 시도하지 마세요. - HTTP
401또는403: 자격 증명을 교체하거나 해당 범위를 수정합니다. - HTTP
429,502,503또는504: 제한된 지수 백오프 및 지터를 사용하여 재시도합니다.
논리적 이벤트에 대해 동일한 event_id를 재사용합니다. 중복 전달을 고려하지 않고 --retry-all-errors를 사용하지 마십시오.
로그 API, 쿼리 API, 테이블 API, 이벤트 전달 가이드를 참조하세요.