기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# NDJSON 엔드포인트를 사용하여 로그 전송(ND-JSON 로그)
ND-JSON Logs 엔드포인트(`/ingest/bulk`)는 [NDJSON(Newline Delimited JSON)](https://github.com/ndjson/ndjson-spec) 형식의 로그를 허용합니다. 각 줄에는 줄 바꿈 문자로 구분된 정확히 하나의 JSON 값이 포함되어 있습니다.
보유자 토큰 인증을 사용하는 경우 계속하기 [보유자 토큰 인증 설정](CWL_HTTP_Endpoints_BearerTokenAuth.md) 전에의 설정 단계를 완료합니다.
## 요청 형식
(LF) 또는 `\n` (`\r\n`CRLF)로 구분하여 줄당 하나의 JSON 값을 전송합니다. 빈 줄은 자동으로 무시됩니다.
```
{"timestamp":1771007942000,"message":"event one","level":"INFO"}
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
{"timestamp":1771007944000,"message":"event three","level":"DEBUG"}
```
`application/json` 및 `application/x-ndjson` 모두 Content-Type으로 허용됩니다.
## 허용되는 JSON 값 유형
NDJSON 사양(RFC 8259)에 따라 유효한 JSON 값은 각 행에서 허용됩니다.
**JSON 객체(가장 일반적):**
```
{"timestamp":1771007942000,"message":"User logged in","service":"auth"}
{"timestamp":1771007943000,"error":"Connection timeout","service":"api"}
```
**JSON 배열(개별 이벤트로 확장됨):**
```
[{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}]
```
이 한 줄은 2개의 이벤트를 생성합니다. 각 배열 요소는 별도의 로그 이벤트가 됩니다.
**기본 값:**
```
"a plain string log message"
42
true
null
```
각 프리미티브는 서버의 현재 타임스탬프가 있는 자체 이벤트가 됩니다.
**혼합 유형:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
4줄 모두 유효한 이벤트로 허용됩니다.
| 라인 콘텐츠 | 동작 |
| --- | --- |
| JSON 객체 | 수락됨, 있는 경우 타임스탬프 추출됨 |
| JSON 배열 | 평면화됨 - 각 요소는 별도의 이벤트가 됩니다. |
| 빈 배열 [] | 수락됨, 이벤트 0개 생성 |
| JSON 문자열 | 이벤트 메시지로 수락됨 |
| JSON 번호 | 이벤트 메시지로 수락됨 |
| JSON 부울 | 이벤트 메시지로 수락됨 |
| JSON null | 이벤트 메시지로 수락됨 |
| 잘못된 JSON | 건너뜀(계산됨, 처리 계속) |
| 빈 줄 | 무시됨( 건너뛴 것으로 계산되지 않음) |
## 타임스탬프 필드
`"timestamp"` 필드는 에포크 밀리초(초 아님) 단위입니다.
| 형식 | 예제 | 다음으로 해석됨 |
| --- | --- | --- |
| 숫자(millis) | "timestamp":1771007942000 | 1771007942000ms |
| 누락됨 | (타임스탬프 필드 없음) | 서버 현재 시간 |
| 숫자가 아닌 | "timestamp":"invalid" | 서버 현재 시간 |
| 비객체 라인 | "hello", 42, true | 서버 현재 시간 |
## 잘못된 줄
유효한 JSON이 아닌 행은 자동으로 건너뛰고 계산됩니다. 처리는 다음 줄로 계속됩니다.
```
{"message":"valid event"}
this is not valid json
{"message":"another valid event"}
```
결과: 2개의 이벤트가 수집되었고 1개를 건너뛰었습니다. `HTTP 200`을 반환합니다.
모든 줄이 유효하지 않은 경우는 `HTTP 400`와 함께를 반환합니다`"All events were invalid"`.
## 요청 예제
```
curl -X POST "https://logs..amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/x-ndjson" \
-d '{"timestamp":1771007942000,"message":"User logged in","level":"INFO"}
{"timestamp":1771007943000,"message":"Query took 42ms","level":"DEBUG"}
{"timestamp":1771007944000,"error":"Connection refused","level":"ERROR"}'
```
## 응답
**성공(모든 이벤트 수락됨):**
```
HTTP 200 OK
{}
```
**부분 성공(일부 이벤트가 거부됨):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
`rejectedLogRecords` 필드는 거부된 총 이벤트 수입니다. `errorMessage` 필드에는 거부 이유별 JSON 인코딩 분류가 포함되어 있습니다.
+ `tooOldLogEventCount` - 보존 기간보다 오래된 타임스탬프가 있는 이벤트
+ `tooNewLogEventCount` - 타임스탬프가 너무 먼 미래의 이벤트
+ `expiredLogEventCount` - 처리 중에 만료된 이벤트
## 모범 사례
### 이벤트 일괄 처리
성능 및 효율성 향상을 위해:
+ 가능한 경우 단일 요청으로 여러 이벤트를 일괄 처리
+ 권장 배치 크기: 요청당 이벤트 10\$1100개
+ 최대 요청 크기: 1MB
### 오류 처리
애플리케이션에서 적절한 오류 처리를 구현합니다. 일반적인 HTTP 상태 코드:
+ `200 OK` - 로그가 성공적으로 수집됨
+ `400 Bad Request` - 잘못된 요청 형식 또는 파라미터
+ `401 Unauthorized` - 유효하지 않거나 만료된 보유자 토큰
+ `403 Forbidden` - 권한 부족
+ `404 Not Found` - 로그 그룹 또는 스트림이 존재하지 않음
+ `429 Too Many Requests` - 속도 제한 초과
+ `500 Internal Server Error` - 서비스 오류(지수 백오프로 재시도)
## 제한 사항
+ 최대 이벤트 크기: 이벤트당 256KB
+ 최대 요청 크기: 1MB
+ 요청당 최대 이벤트 수: 10,000
+ 로그 그룹 이름은 CloudWatch Logs 명명 규칙을 따라야 합니다.
+ 보유자 토큰 인증을 사용하는 경우 로그 그룹에서 보유자 토큰 인증을 활성화해야 합니다.