HTTP 엔드포인트를 통한 로그 수집 - Amazon CloudWatch Logs
일반적인 동작HTTP 수집 엔드포인트 비교엔드포인트 선택

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

HTTP 엔드포인트를 통한 로그 수집

Amazon CloudWatch Logs는 간단한 HTTP POST 요청을 사용하여 CloudWatch Logs로 직접 로그를 전송할 수 있는 HTTP 엔드포인트를 제공합니다. 이러한 엔드포인트는 SigV4 및 보유자 토큰 인증을 모두 지원합니다.

중요

AWS SDK 통합이 가능한 모든 프로덕션 워크로드에 SigV4 인증을 사용하는 것이 좋습니다. SigV4는 단기 자격 증명을 사용하고 가장 강력한 보안 태세를 제공합니다. 베어러 토큰(API 키) 인증은 AWS SDK 통합을 지원하지 않는 타사 로그 전달자와 같이 SigV4가 불가능한 시나리오를 위한 것입니다. 자세한 내용은 IAM 사용 설명서의 장기 액세스 키의 대안을 참조하세요.

CloudWatch Logs는 다음 HTTP 수집 엔드포인트를 지원합니다.

엔드포인트 경로 Content-Type 형식
OpenTelemetry Logs /v1/logs application/json 또는 application/x-protobuf OTLP JSON 또는 Protobuf
HLC Logs /services/collector/event application/json HLC 형식
ND-JSON Logs /ingest/bulk application/json 또는 application/x-ndjson 줄 바꿈으로 구분된 JSON
Structured JSON Logs /ingest/json application/json JSON 객체 또는 배열

일반적인 동작

모든 HTTP 수집 엔드포인트는 다음 동작을 공유합니다.

Authentication

모든 엔드포인트는 SigV4 및 보유자 토큰 인증을 모두 지원합니다.

  • SigV4(권장) - 표준 AWS 서명 버전 4 서명. 애플리케이션 또는 인프라가 AWS SDK를 지원하거나 요청에 서명할 수 있을 때마다 SigV4를 사용합니다. SigV4는 단기 자격 증명을 사용하며 가장 안전한 인증 방법입니다.

  • 베어러 토큰 - Authorization: Bearer <ACWL token> 헤더를 사용합니다.

    • 토큰은 유효한 ACWL 보유자 토큰이어야 합니다. 설정 지침은 단원을 참조하십시오보유자 토큰 인증 설정.

    • logs:PutLogEvents 및 logs:CallWithBearerToken IAM 권한이 필요합니다.

로그 그룹 및 로그 스트림

  • 헤더를 통해 제공: x-aws-log-group 및 x-aws-log-stream

  • 쿼리 파라미터?logGroup=<name>&logStream=<name>는 OTLP를 제외한 모든 엔드포인트에서도 지원됩니다.

  • 동일한 파라미터에 대해 쿼리 파라미터와 헤더를 모두 사용할 수는 없습니다.

  • 로그 그룹과 로그 스트림이 모두 필요합니다.

응답

  • 성공: 본문 HTTP 200 포함 {}

  • 검증 오류: HTTP 400

  • 인증 실패: HTTP 401

HTTP 수집 엔드포인트 비교

기능 HLC 로그 ND-JSON 로그 구조화된 JSON 로그 OpenTelemetry 로그
경로 /services/collector/event /ingest/bulk /ingest/json /v1/logs
Content-Type application/json application/json 또는 application/x-ndjson application/json application/json 또는 application/x-protobuf
타임스탬프 필드 "time"(초) "timestamp" (밀리초) "timestamp" (밀리초) "timeUnixNano" (나노초)
필수 필드 "event" 없음 없음 OTLP 구조("resourceLogs")
부분 성공 응답 아니요 예 예 예
쿼리 파라미터 지원 예 예 예 아니요(헤더만 해당)
개체 메타데이터 예 예 예 아니요
프리미티브 허용 아니요 예 아니요 아니요
라인 기반 구문 분석 아니요 예 아니요 아니요
Protobuf 지원 아니요 아니요 아니요 예
재시도 후 헤더 아니요 아니요 아니요 예

엔드포인트 선택

  • HLC 형식을 사용하시나요? HLC 로그를 사용합니다. 기존 HLC 페이로드는 최소한의 변경으로 작동합니다.

  • line-by-line 로그 스트리밍? ND-JSON 로그를 사용합니다. 행당 하나의 이벤트를 내보내는 로그 파이프라인에 가장 적합합니다. 가장 유연함 - 모든 JSON 값 유형을 허용합니다.

  • 구조화된 JSON 페이로드를 보내나요? 구조화된 JSON 로그를 사용합니다. 올바른 형식의 JSON 객체 또는 배열을 생성하는 애플리케이션에 가장 적합합니다.

  • 이미 OpenTelemetry를 사용하고 있나요? OpenTelemetry Logs를 사용합니다. OTLP JSON 또는 Protobuf 형식을 수락하고 재시도 의미 체계를 사용하여 부분 성공 응답을 지원합니다.