로그
로그 API는 이벤트를 Telemetry에 수집하는 방법입니다. 애플리케이션 이벤트, 사용자 활동, 메트릭 또는 구조화된 로그에 사용하세요.
Telemetry는 저장 전에 테이블 이름과 타임스탬프를 정규화하고 null 값, 빈 객체, 빈 배열을 제거합니다.
포스트 https://api.telemetry.sh/log
헤더
| 이름 | 유형 | 설명 |
|---|---|---|
| 콘텐츠 유형 | 문자열 | 애플리케이션/json |
| 승인 | 문자열 | API 키(원본 키 또는 Bearer <key>) |
본문
| 이름 | 유형 | 설명 |
|---|---|---|
| 테이블 | 문자열 | 대상 테이블 이름입니다. 공백은 밑줄로 변환되고 문자는 소문자로 변환되며 정규화 후에는 소문자 ASCII 문자, 숫자 및 _만 허용됩니다. |
| 데이터 | JSON | 이벤트 페이로드. 지원되는 모양은 JSON 개체, JSON 개체의 배열, JSON 개체로 디코딩되는 JSON 문자열 또는 JSON 개체와 디코딩되는 JSON 문자열을 혼합하는 배열입니다. JSON 객체. |
허용되는 데이터 형태
API는 다음을 허용합니다.
- 단일 JSON 개체
- JSON 객체의 배열
- 자체적으로 JSON 객체로 구문 분석되는 JSON 문자열
- JSON 객체와 JSON 객체로 구문 분석되는 JSON 문자열을 포함하는 배열
API는 다음을 거부합니다.
- 최상위 숫자, 부울 및
null - 배열, 숫자, 부울 또는
null와 같은 비객체 값으로 디코딩하는 JSON 문자열 - 비객체, 비문자열 항목을 포함하는 배열
- 객체가 아닌 값으로 디코딩되는 JSON 문자열을 포함하는 배열
- JSON 페이로드가 64레벨보다 깊게 중첩됨
- 빈 이벤트 배치,
data: []
서버측 정규화
data에 JSON 객체가 포함된 경우 Telemetry는 수집 전에 다음 규칙을 적용합니다.
- 현재 UTC 시간이 누락된 경우
timestamp를 추가합니다. timestamp가null인 경우 현재 UTC 시간으로 바꿉니다.timestamp가 Unix 타임스탬프 정수 또는 숫자 문자열인 경우 Unix 초로 해석하여 RFC 3339로 변환합니다.timestamp_utc가 있는 경우 제거합니다.null값, 빈 객체, 빈 배열을 재귀적으로 제거합니다."",0,false는 유지합니다.
예:
Telemetry Events는telemetry_events가 됩니다.timestamp: 1700000000는 RFC 3339 타임스탬프 문자열이 됩니다.{ "user": "alice", "meta": null }는meta없이 저장됩니다.
cURL을 사용한 사용 예
cURL을 사용하여 Uber 탑승 데이터를 uber_rides라는 테이블로 보내려면 다음 명령을 사용할 수 있습니다.
curl -X POST https://api.telemetry.sh/log \
-H "Content-Type: application/json" \
-H "Authorization: $API_KEY" \
-d '{
"table": "uber_rides",
"data": {
"city": "paris",
"price": 42
}
}'
JavaScript SDK 사용
더 나은 개발자 경험을 위해 SDK를 사용하는 것이 좋습니다. 다음은 JavaScript SDK를 사용하는 방법의 예입니다.
import telemetry from "telemetry-sh";
telemetry.init("YOUR_API_KEY");
telemetry.log("uber_rides", {
city: "paris",
price: 42
});
대량 로깅
이벤트를 대량으로 수집하기 위해 객체 배열을 전달할 수도 있습니다. 이는 API에 대한 요청 수를 제한하는 데 유용합니다. 예를 들면 다음과 같습니다.
telemetry.log("uber_rides", { a: 1 })
당신은 할 수 있습니다 :
telemetry.log("uber_rides", [{a: 1}, {a: 2}])
그러면 데이터가 두 개의 행으로 수집됩니다.
일반적인 오류
- JSON 본문이 유효하지 않은 경우
400 Bad Request - 정규화 후 테이블 이름에 잘못된 문자가 포함된 경우
400 Bad Request data가 지원되는 모양이 아닌 경우400 Bad Requestdata가 빈 배열이면400 Bad Request와 오류 코드empty_batch를 반환합니다. 이벤트를 하나 이상 보내세요. 페이로드 크기를 줄여도 이 오류는 해결되지 않습니다.data의 JSON 문자열이 비객체 값으로 디코딩되는 경우400 Bad Request- Unix 타임스탬프가 지원되는 범위를 벗어난 경우
400 Bad Request - API 키가 없거나 잘못된 경우
401 Unauthorized - API 키가 게이트웨이 속도 제한을 초과하는 경우
429 Too Many Requests