기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# HTTP 엔드포인트를 통한 로그 수집
Amazon CloudWatch Logs는 간단한 HTTP POST 요청을 사용하여 CloudWatch Logs로 직접 로그를 전송할 수 있는 HTTP 엔드포인트를 제공합니다. 이러한 엔드포인트는 SigV4 및 보유자 토큰 인증을 모두 지원합니다.
**중요**
AWS SDK 통합이 가능한 모든 프로덕션 워크로드에 SigV4 인증을 사용하는 것이 좋습니다. SigV4는 단기 자격 증명을 사용하고 가장 강력한 보안 태세를 제공합니다. 베어러 토큰(API 키) 인증은 AWS SDK 통합을 지원하지 않는 타사 로그 전달자와 같이 SigV4가 불가능한 시나리오를 위한 것입니다. 자세한 내용은 *IAM 사용 설명서*의 [장기 액세스 키의 대안](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)을 참조하세요.
CloudWatch Logs는 다음 HTTP 수집 엔드포인트를 지원합니다.
| 엔드포인트 | 경로 | Content-Type | 형식 |
| --- | --- | --- | --- |
| [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json 또는 application/x-protobuf | OTLP JSON 또는 Protobuf |
| [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | HLC 형식 |
| [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json 또는 application/x-ndjson | 줄 바꿈으로 구분된 JSON |
| [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | JSON 객체 또는 배열 |
## 일반적인 동작
모든 HTTP 수집 엔드포인트는 다음 동작을 공유합니다.
**Authentication**
모든 엔드포인트는 SigV4 및 보유자 토큰 인증을 모두 지원합니다.
+ **SigV4(권장)** - 표준 AWS 서명 버전 4 서명. 애플리케이션 또는 인프라가 AWS SDK를 지원하거나 요청에 서명할 수 있을 때마다 SigV4를 사용합니다. SigV4는 단기 자격 증명을 사용하며 가장 안전한 인증 방법입니다.
+ **베어러 토큰** - `Authorization: Bearer ` 헤더를 사용합니다.
+ 토큰은 유효한 ACWL 보유자 토큰이어야 합니다. 설정 지침은 단원을 참조하십시오[보유자 토큰 인증 설정](CWL_HTTP_Endpoints_BearerTokenAuth.md).
+ `logs:PutLogEvents` 및 `logs:CallWithBearerToken` IAM 권한이 필요합니다.
**로그 그룹 및 로그 스트림**
+ 헤더를 통해 제공: `x-aws-log-group` 및 `x-aws-log-stream`
+ 쿼리 파라미터`?logGroup=&logStream=`는 OTLP를 제외한 모든 엔드포인트에서도 지원됩니다.
+ 동일한 파라미터에 대해 쿼리 파라미터와 헤더를 모두 사용할 수는 없습니다.
+ 로그 그룹과 로그 스트림이 모두 필요합니다.
**응답**
+ 성공: 본문 `HTTP 200` 포함 `{}`
+ 검증 오류: `HTTP 400`
+ 인증 실패: `HTTP 401`
# 보유자 토큰 인증 설정
HTTP 수집 엔드포인트에서 보유자 토큰 인증을 사용하여 로그를 전송하려면 먼저 다음을 수행해야 합니다.
+ CloudWatch Logs 권한이 있는 IAM 사용자 생성
+ 서비스별 자격 증명 생성(베어러 토큰)
+ 로그 그룹 및 로그 스트림 생성
+ 로그 그룹에서 보유자 토큰 인증 활성화
**중요**
가능한 경우 모든 워크로드에 대해 단기 자격 증명과 함께 SigV4 인증을 사용하는 것이 좋습니다. SigV4는 가장 강력한 보안 태세를 제공합니다. API 키(베어러 토큰) 사용을 단기 자격 증명 기반 인증이 불가능한 시나리오로 제한합니다. 보안 요구 사항이 더 큰 애플리케이션에 CloudWatch Logs를 통합할 준비가 되면 단기 자격 증명으로 전환해야 합니다. 자세한 내용은 *IAM 사용 설명서*의 [장기 액세스 키의 대안](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)을 참조하세요.
## 옵션 1: AWS 콘솔을 사용하여 빠른 시작
AWS Management Console은 HTTP 엔드포인트 액세스를 위한 API 키를 생성하는 간소화된 워크플로를 제공합니다.
**콘솔을 사용하여 HTTP 엔드포인트 액세스를 설정하려면**
1. AWS Management Console에 로그인합니다.
1. **CloudWatch** > **설정** > **로그**로 이동합니다.
1. API 키 섹션에서 **API 키 생성을** 선택합니다.
1. **API 키 만료**가 된 경우 다음 중 하나를 수행하세요..
+ **1**, **5**, **30**, **9**0 또는 **365**일의 API 키 만료 기간을 선택합니다.
+ **사용자 지정 기간**을 선택하여 사용자 지정 API 키 만료 날짜를 지정합니다.
+ **만료되지 않음을** 선택합니다(권장되지 않음).
1. **API 키 생성**을 선택합니다.
콘솔은 자동으로 다음을 수행합니다.
+ 적절한 권한을 가진 새 IAM 사용자를 생성합니다.
+ [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) 관리형 정책( `logs:PutLogEvents` 및 `logs:CallWithBearerToken` 권한 포함)을 연결합니다.
+ 서비스별 자격 증명(API 키)을 생성합니다.
1. 표시된 자격 증명을 복사하고 안전하게 저장합니다.
+ **API 키 ID**(서비스별 자격 증명 ID)
+ **API 키 보안** 암호(베어러 토큰)
**중요**
API 키 보안 암호를 즉시 저장합니다. 나중에는 조회할 수 없습니다. 분실한 경우 새 API 키를 생성해야 합니다.
1. 로그가 저장될 로그 그룹 및 로그 스트림을 생성합니다.
```
# Create the log group
aws logs create-log-group \
--log-group-name /aws/hlc-logs/my-application \
--region us-east-1
# Create the log stream
aws logs create-log-stream \
--log-group-name /aws/hlc-logs/my-application \
--log-stream-name application-stream-001 \
--region us-east-1
```
1. 로그 그룹에서 보유자 토큰 인증을 활성화합니다.
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
구성을 확인합니다.
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
**포함된 권한:** 자동으로 생성된 IAM 사용자에게는 다음과 같은 권한이 있습니다.
+ `logs:PutLogEvents` - CloudWatch Logs로 로그 이벤트 전송
+ `logs:CallWithBearerToken` - 보유자 토큰을 사용하여 인증
+ `kms:Describe*`, `kms:GenerateDataKey*`, `kms:Decrypt` - KMS로 암호화된 로그 그룹에 액세스(로그 서비스로 제한되는 조건 사용)
## 옵션 2: 수동 설정
IAM 구성에 대한 더 많은 제어를 원하거나 권한을 사용자 지정해야 하는 경우 HTTP 엔드포인트 액세스를 수동으로 설정할 수 있습니다.
### 1단계: IAM 사용자 생성
로그 수집에 사용할 IAM 사용자를 생성합니다.
1. AWS Management Console에 로그인하고 IAM으로 이동합니다.
1. 왼쪽 탐색 창에서 **사용자**를 선택합니다.
1. **사용자 생성**을 선택합니다.
1. 사용자 이름(예: `cloudwatch-logs-hlc-user`)을 입력합니다.
1. **다음**을 선택합니다.
1. 다음 IAM 정책 중 하나를 연결합니다.
**옵션 A: 관리형 정책 사용(권장)**
[CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) 관리형 정책을 연결합니다.
**옵션 B: 사용자 지정 정책 생성**
다음 IAM 정책을 생성하고 연결합니다.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LogsAPIs",
"Effect": "Allow",
"Action": [
"logs:CallWithBearerToken",
"logs:PutLogEvents"
],
"Resource": "*"
},
{
"Sid": "KMSAPIs",
"Effect": "Allow",
"Action": [
"kms:Describe*",
"kms:GenerateDataKey*",
"kms:Decrypt"
],
"Condition": {
"StringEquals": {
"kms:ViaService": [
"logs.*.amazonaws.com"
]
}
},
"Resource": "arn:aws:kms:*:*:key/*"
}
]
}
```
1. **다음을** 선택한 후 **사용자 생성을** 선택합니다.
**참고**
KMS 암호화 로그 그룹에 로그를 보내려는 경우 KMS 권한이 필요합니다. 이 조건은 KMS 액세스를 CloudWatch Logs 서비스를 통해 사용되는 키로만 제한합니다.
### 2단계: 서비스별 자격 증명 생성(API 키)
[CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html) API를 사용하여 CloudWatch Logs API 키를 생성합니다. [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html) CLI 명령을 사용할 수도 있습니다. 자격 증명 기간에 대해 1\$136600일 사이의 값을 지정할 수 있습니다. 자격 증명 기간을 지정하지 않으면 API 키가 만료되지 않습니다.
만료 기간이 30일인 API 키를 생성하려면:
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 30
```
응답은 [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html) 객체입니다. `ServiceCredentialSecret` 값은 CloudWatch Logs API 키(베어러 토큰)입니다.
**중요**
나중에 검색할 수 없으므로 `ServiceCredentialSecret` 값을 안전하게 저장하세요. 분실한 경우 새 API 키를 생성해야 합니다.
### 3단계: 로그 그룹 및 로그 스트림 생성
로그가 저장될 로그 그룹 및 로그 스트림을 생성합니다.
```
# Create the log group
aws logs create-log-group \
--log-group-name /aws/hlc-logs/my-application \
--region us-east-1
# Create the log stream
aws logs create-log-stream \
--log-group-name /aws/hlc-logs/my-application \
--log-stream-name application-stream-001 \
--region us-east-1
```
### 4단계: 보유자 토큰 인증 활성화
로그 그룹에서 보유자 토큰 인증을 활성화합니다.
```
aws logs put-bearer-token-authentication \
--log-group-identifier /aws/hlc-logs/my-application \
--bearer-token-authentication-enabled \
--region us-east-1
```
구성을 확인합니다.
```
aws logs describe-log-groups \
--log-group-name-prefix /aws/hlc-logs/my-application \
--region us-east-1
```
## CloudWatch Logs API 키 생성 및 사용에 대한 권한 제어
CloudWatch Logs API 키의 생성 및 사용은 CloudWatch Logs 및 IAM 서비스 모두에서 작업 및 조건 키로 제어됩니다.
### CloudWatch Logs API 키 생성 제어
[iam:CreateServiceSpecificCredential](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) 작업은 서비스별 키(예: CloudWatch Logs API 키)의 생성을 제어합니다. 이 작업의 범위를 리소스인 IAM 사용자로 지정하여 키를 생성할 수 있는 사용자를 제한할 수 있습니다.
다음 조건 키를 사용하여 `iam:CreateServiceSpecificCredential` 작업에 대한 권한에 조건을 적용할 수 있습니다.
+ [iam:ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) - 조건에서 키의 만료 시간을 일 단위로 지정할 수 있습니다. 예를 들어, 이 조건 키를 사용하여 90일 이내에 만료되는 API 키의 생성만 허용할 수 있습니다.
+ [iam:ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) - 조건에서 서비스 이름을 지정할 수 있습니다. 예를 들어이 조건 키를 사용하여 다른 서비스가 아닌 CloudWatch Logs에 대한 API 키 생성만 허용할 수 있습니다.
### CloudWatch Logs API 키 사용 제어
`logs:CallWithBearerToken` 작업은 CloudWatch Logs API 키의 사용을 제어합니다. 자격 증명이 CloudWatch Logs API 키를 사용하지 못하도록 하려면 키와 연결된 IAM 사용자에게 `logs:CallWithBearerToken` 작업을 거부하는 정책을 연결합니다.
### 정책 예제
#### 자격 증명이 CloudWatch Logs API 키를 생성하고 사용하지 못하도록 방지
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyCWLAPIKeys",
"Effect": "Deny",
"Action": [
"iam:CreateServiceSpecificCredential",
"logs:CallWithBearerToken"
],
"Resource": "*"
}
]
}
```
**주의**
이 정책은 AWS 서비스별 자격 증명 생성을 지원하는 모든 서비스에 대한 자격 증명 생성을 방지합니다. 자세한 내용은 [IAM 사용자를 위한 서비스별 자격 증명](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html)을 참조하세요.
#### 자격 증명이 CloudWatch Logs API 키를 사용하지 못하도록 방지
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
]
}
```
#### 90일 이내에 만료되는 경우에만 CloudWatch Logs 키 생성 허용
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceSpecificCredential",
"Resource": "arn:aws:iam::123456789012:user/username",
"Condition": {
"StringEquals": {
"iam:ServiceSpecificCredentialServiceName": "logs.amazonaws.com"
},
"NumericLessThanEquals": {
"iam:ServiceSpecificCredentialAgeDays": "90"
}
}
}
]
}
```
## API 키 교체
API 키를 정기적으로 교체하면 무단 액세스 위험이 줄어듭니다. 조직의 보안 정책에 맞는 교체 일정을 설정하는 것이 좋습니다.
### 교체 프로세스
로그 전송을 중단하지 않고 API 키를 교체하려면 다음 절차를 따르세요.
1. IAM 사용자를 위한 새 (보조) 자격 증명을 생성합니다.
```
aws iam create-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com \
--credential-age-days 90
```
1. (선택 사항) 보안 검색 및 자동 교체를 AWS Secrets Manager 위해에 새 자격 증명을 저장합니다.
1. 새 자격 증명을 공급업체의 포털로 가져오거나 새 API 키를 사용하도록 애플리케이션 구성을 업데이트합니다.
1. 원래 자격 증명을 비활성으로 설정합니다.
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. CloudWatch에서 로그 그룹의 `IncomingBytes` 지표를 모니터링하여 로그 전송이 영향을 받지 않는지 확인합니다. 자세한 내용은 [CloudWatch 지표를 사용한 모니터링](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)을 참조하세요.
1. 새 키로 전송 성공 여부를 확인한 후 이전 자격 증명을 삭제합니다.
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
### 키 만료 모니터링
기존 API 키의 생성 날짜 및 상태를 확인하려면 [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html) 명령을 사용합니다.
```
aws iam list-service-specific-credentials \
--user-name cloudwatch-logs-hlc-user \
--service-name logs.amazonaws.com
```
응답에는 각 자격 증명`Status`에 대한 `CreateDate` 및가 포함됩니다. 이 정보를 사용하여 만료에 가까워지거나 교체 정책에서 허용하는 것보다 오래 활성화된 키를 식별할 수 있습니다.
## 손상된 API 키에 대한 응답
API 키가 손상되었다고 의심되는 경우 즉시 다음 단계를 수행합니다.
1. 추가 무단 사용을 방지하려면 **키를 즉시 비활성화합니다**.
```
aws iam update-service-specific-credential \
--user-name cloudwatch-logs-hlc-user \
--service-specific-credential-id ACCA1234EXAMPLE1234 \
--status Inactive
```
1. **CloudTrail 로그를 검토하여** 무단 액세스 범위를 결정합니다. API 키 사용에 [CloudTrail을 사용하여 API 키 사용량 로깅](#CWL_HTTP_Endpoints_CloudTrail_Logging) 대한 감사를 활성화하는 방법은 섹션을 참조하세요.
1. 에 설명된 교체 프로세스에 따라 **대체 키를 생성합니다**[교체 프로세스](#CWL_HTTP_Endpoints_Rotation_Process).
1. 교체가 적용된 후 **손상된 키를 삭제**합니다.
```
aws iam delete-service-specific-credential \
--service-specific-credential-id ACCA1234EXAMPLE1234
```
1. 조사하는 동안 IAM 사용자의 모든 보유자 토큰 액세스를 즉시 차단해야 하는 경우 **거부 정책을 연결합니다**.
```
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "logs:CallWithBearerToken",
"Resource": "*"
}
}
```
**참고**
API를 통해 이러한 작업을 수행하려면 CloudWatch Logs API 키가 아닌 AWS 자격 증명으로 인증해야 합니다.
다음 IAM API 작업을 사용하여 손상된 키를 관리할 수도 있습니다.
+ [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html) - 자격 증명을 삭제하지 않고 새 암호를 생성하려면 키를 재설정합니다. 키가 만료되지 않았어야 합니다.
## API 키에 대한 보안 모범 사례
CloudWatch Logs API 키를 보호하려면 다음 모범 사례를 따르세요.
+ **소스 코드에 API 키를 포함시키지 마십시오.** 애플리케이션 코드에서 API 키를 하드 코딩하거나 버전 제어 시스템에 커밋하지 마십시오. 키가 실수로 퍼블릭 리포지토리에 커밋된 경우 AWS 자동 스캔에서 해당 키에 플래그가 지정될 수 있으므로 키를 즉시 교체해야 합니다.
+ **보안 암호 관리자를 사용합니다.** API 키를 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 또는 이에 상응하는 보안 암호 관리 솔루션에 저장합니다. 이를 통해 중앙 집중식 액세스 제어, 감사 로깅 및 자동 교체가 가능합니다.
+ **모든 키에 만료를 설정합니다.** API 키를 생성할 때는 항상 `--credential-age-days` 값을 지정합니다. 조직 전체에 최대 키 수명을 적용하려면 `iam:ServiceSpecificCredentialAgeDays` IAM 조건 키를 사용합니다. 예제는 [90일 이내에 만료되는 경우에만 CloudWatch Logs 키 생성 허용](#CWL_HTTP_Endpoints_Allow_Expire_90) 섹션을 참조하세요.
+ **최소 권한 권한을 적용합니다.** IAM 사용자의 권한 범위를 필요한 로그 그룹 및 작업으로만 지정합니다. 관리형 [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) 정책을 시작점으로 사용하고 필요에 따라 추가로 제한합니다.
+ **CloudTrail 로깅을 활성화합니다.** 에 대한 CloudTrail 데이터 이벤트를 활성화하여 API 키 사용을 감사합니다`AWS::Logs::LogGroupAuthorization`. [CloudTrail을 사용하여 API 키 사용량 로깅](#CWL_HTTP_Endpoints_CloudTrail_Logging)을(를) 참조하세요.
+ **IAM Access Analyzer로 모니터링합니다.** [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html)를 사용하여 API 키 IAM 사용자와 연결된 미사용 자격 증명 및 지나치게 허용적인 정책을 식별합니다.
+ **키를 정기적으로 교체합니다.** 교체 일정을 설정하고에 설명된 프로세스를 따릅니다[API 키 교체](#CWL_HTTP_Endpoints_Rotating_Keys).
## CloudTrail을 사용하여 API 키 사용량 로깅
AWS CloudTrail 를 사용하여 CloudWatch Logs API 키 사용에 대한 데이터 이벤트를 로깅할 수 있습니다. CloudWatch Logs는 `CallWithBearerToken` 호출에 대한 `AWS::Logs::LogGroupAuthorization` 데이터 이벤트를 내보내므로 API 키를 사용하여 로그를 전송하는 시기와 방법을 감사할 수 있습니다.
CloudWatch Logs API 키 사용에 대해 CloudTrail 로깅을 활성화하려면: CloudWatch
**참고**
추적에 지정하는 S3 버킷에는 CloudTrail이 로그 파일을 쓸 수 있도록 허용하는 버킷 정책이 있어야 합니다. 자세한 내용은 [ CloudTrail에 대한 Amazon S3 버킷 정책을](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html) 참조하세요.
1. 추적 생성:
```
aws cloudtrail create-trail \
--name cloudwatch-logs-api-key-audit \
--s3-bucket-name my-cloudtrail-bucket \
--region us-east-1
```
1. CloudWatch Logs 로그 그룹 권한 부여 이벤트를 캡처하도록 고급 이벤트 선택기를 구성합니다.
```
aws cloudtrail put-event-selectors \
--region us-east-1 \
--trail-name cloudwatch-logs-api-key-audit \
--advanced-event-selectors '[{
"Name": "CloudWatch Logs API key authorization events",
"FieldSelectors": [
{ "Field": "eventCategory", "Equals": ["Data"] },
{ "Field": "resources.type", "Equals": ["AWS::Logs::LogGroupAuthorization"] }
]
}]'
```
1. 추적 로깅 시작:
```
aws cloudtrail start-logging \
--name cloudwatch-logs-api-key-audit \
--region us-east-1
```
# OTLP 엔드포인트를 사용하여 로그 전송(OpenTelemetry Logs)
OpenTelemetry Logs 엔드포인트(`/v1/logs`)는 JSON 또는 Protobuf 인코딩의 OpenTelemetry Protocol(OTLP) 로그 데이터를 수락합니다. 구성 및 사용량을 포함하여 OTLP 엔드포인트에 대한 자세한 내용은 [ OpenTelemetry를 사용하여 CloudWatch로 지표 및 추적 전송을 참조하세요](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html).
보유자 토큰 인증을 사용하는 경우 계속하기 [보유자 토큰 인증 설정](CWL_HTTP_Endpoints_BearerTokenAuth.md) 전에의 설정 단계를 완료합니다.
## 요청 형식
+ 메서드: `POST`
+ Content-Type: `application/json` 또는 `application/x-protobuf`
+ 로그 그룹: `x-aws-log-group` 헤더만(쿼리 파라미터는 지원되지 않음)
+ 로그 스트림: `x-aws-log-stream` 헤더
## 요청 예제
```
curl -X POST "https://logs..amazonaws.com/v1/logs" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-H "x-aws-log-group: MyLogGroup" \
-H "x-aws-log-stream: MyLogStream" \
-d '{
"resourceLogs": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": { "stringValue": "my-service" }
}
]
},
"scopeLogs": [
{
"scope": {
"name": "my-library",
"version": "1.0.0"
},
"logRecords": [
{
"timeUnixNano": "1741900000000000000",
"severityNumber": 9,
"severityText": "INFO",
"body": {
"stringValue": "User logged in successfully"
},
"attributes": [
{
"key": "user.id",
"value": { "stringValue": "12345" }
}
]
}
]
}
]
}
]
}'
```
## 응답
**성공(모든 이벤트 수락됨):**
```
HTTP 200 OK
{}
```
**부분 성공(일부 이벤트가 거부됨):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
요청 Content-Type이 인 경우 `application/x-protobuf`응답은 필드가 동일한 직렬화된 `ExportLogsServiceResponse` protobuf 메시지로 반환됩니다.
## OTLP 관련 동작
다음 동작은 OTLP 엔드포인트에 고유하며 다른 HTTP 수집 엔드포인트에는 없습니다.
+ **Retry-After 헤더** - 클라이언트가 언제 재시도해야 하는지를 나타내는 503 및 429 응답에 포함됩니다.
# HLC 엔드포인트를 사용하여 로그 전송(HLC 로그)
HLC Logs 엔드포인트(`/services/collector/event`)는 HTTP Log Collector(HLC) 형식을 기반으로 합니다.
보유자 토큰 인증을 사용하는 경우 계속하기 [보유자 토큰 인증 설정](CWL_HTTP_Endpoints_BearerTokenAuth.md) 전에의 설정 단계를 완료합니다.
## 입력 모드
각 이벤트는 필수 `"event"` 필드가 있는 JSON 객체입니다. 선택적 메타데이터 필드: `"time"`, `"host"`, `"source"`, `"sourcetype"`, `"index"`.
**단일 이벤트:**
```
{"event":"Hello world!","time":1486683865.0}
```
**이벤트의 JSON 배열:**
```
[
{"event":"msg1","time":1486683865.0},
{"event":"msg2","time":1486683866.0}
]
```
**연결된/배치된 이벤트(어레이 래퍼 없음):**
```
{"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0}
```
## 이벤트 필드(필수)
`"event"` 필드는 필수입니다. 값은 모든 JSON 유형일 수 있습니다.
```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```
`"event"` 필드가 없는 객체는 자동으로 건너뜁니다.
```
{"message":"this is skipped — no event field"}
```
## 시간 필드(선택 사항)
`"time"` 필드는 에포크 초(밀리초 아님) 단위이며, 10진수는 1초 미만의 정밀도에 대한 선택적 10진수입니다.
| 형식 | 예제 | 다음으로 해석됨 |
| --- | --- | --- |
| Float | "time":1486683865.500 | 1486683865500ms |
| Integer | "time":1486683865 | 1486683865000ms |
| 문자열(부동 소수점) | "time":"1486683865.500" | 1486683865500ms |
| 문자열(정수) | "time":"1486683865" | 1486683865000ms |
| 누락됨 | (시간 필드 없음) | 서버 현재 시간 |
| 잘못됨 | "time":"invalid" | 서버 현재 시간 |
## Content-Type
만 `application/json` 허용됩니다.
## 허용되는 JSON 값 유형
| 최상위 유형 | 동작 |
| --- | --- |
| 가 있는 객체 "event" | 수락됨 |
| 가 없는 객체 "event" | 건너뜀 |
| 객체 배열 | 개별적으로 처리되는 각 요소 |
| 연결된 객체 | 개별적으로 처리되는 각 객체 |
| 프리미티브(문자열, 숫자, 부울, null) | 건너뜀 |
## 엔드포인트 형식
HLC 엔드포인트 URL은 다음 형식을 따릅니다.
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**필수 파라미터:**
+ `` – AWS 리전(예: , `us-east-1``eu-west-1`)
+ `logGroup` - URL로 인코딩된 로그 그룹 이름
+ `logStream` - URL로 인코딩된 로그 스트림 이름
**선택적 파라미터:**
필요에 따라 다음 쿼리 파라미터를 포함하여 로그 이벤트를 `Service`엔터티와 연결할 수 있습니다. HLC 엔드포인트를 통해 전송된 로그는 사용자 지정 원격 측정이므로 엔터티와 자동으로 연결되지 않습니다. CloudWatch Logs는 이러한 파라미터를 제공하여가 로 `KeyAttributes.Type` 설정된 개체를 생성하고 이를 로그 이벤트와 `Service` 연결합니다. 이를 통해 CloudWatch의 **관련 기능 탐색**은 이러한 로그를 동일한 서비스의 다른 원격 측정(지표, 추적 및 로그)과 상호 연관시킬 수 있으므로 다양한 신호 유형에서 애플리케이션의 문제를 더 쉽게 해결하고 모니터링할 수 있습니다. 개체 및 관련 원격 측정에 대한 자세한 내용은 [사용자 지정 원격 측정에 관련 정보 추가](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html)를 참조하세요.
+ `entityName` - 로그 이벤트와 연결할 서비스 엔터티의 이름입니다. 이 값은 엔터티`KeyAttributes.Name`(예: `my-application` 또는 `api.myservice.com`)로 저장됩니다.
+ `entityEnvironment` - 서비스가 호스팅되는 환경 또는 서비스가 속한 환경입니다. 이 값은 개체`KeyAttributes.Environment`(예: , `production` `ec2:default`또는 `eks:my-cluster/default`)로 저장됩니다.
## 요청 형식
다음 헤더 및 본문과 함께 HTTP POST를 사용하여 로그를 전송합니다.
**헤더:**
+ `Authorization: Bearer `
+ `Content-Type: application/json`
**본문 형식:**
요청 본문은 이벤트 배열과 함께 JSON 형식이어야 합니다.
```
{
"event": [
{
"time": 1730141374.001,
"event": "Application started successfully",
"host": "web-server-1",
"source": "application.log",
"severity": "info"
},
{
"time": 1730141374.457,
"event": "User login successful",
"host": "web-server-1",
"source": "auth.log",
"user": "john.doe"
}
]
}
```
**필드 설명**:
+ `time` - Unix epoch 타임스탬프, 1초 미만의 정밀도에 대한 선택적 10진수(선택 사항)
+ `event` - 로그 메시지 또는 이벤트 데이터(필수)
+ `host` - 소스 호스트 이름 또는 식별자(선택 사항)
+ `source` - 로그 소스 식별자(선택 사항)
필요에 따라 추가 사용자 지정 필드를 포함할 수 있습니다.
## 요청 예제
```
curl -X POST "https://logs..amazonaws.com/services/collector/event?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-d '{"event":{"message":"User logged in","user_id":"u-123"},"time":1486683865.0,"host":"web-01","source":"auth-service"}'
```
## 모범 사례
### 이벤트 일괄 처리
성능 및 효율성 향상을 위해:
+ 가능한 경우 단일 요청으로 여러 이벤트 배치
+ 권장 배치 크기: 요청당 이벤트 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 명명 규칙을 따라야 합니다.
+ 보유자 토큰 인증을 사용하는 경우 로그 그룹에서 보유자 토큰 인증을 활성화해야 합니다.
# 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 명명 규칙을 따라야 합니다.
+ 보유자 토큰 인증을 사용하는 경우 로그 그룹에서 보유자 토큰 인증을 활성화해야 합니다.
# 구조화된 JSON 엔드포인트를 사용하여 로그 전송(구조화된 JSON 로그)
구조화된 JSON 로그 엔드포인트(`/ingest/json`)는 단일 JSON 객체 또는 객체의 JSON 배열인 표준 JSON을 허용합니다. 이 엔드포인트는 각 이벤트가 JSON 객체인 구조화된 로그 데이터를 위해 설계되었습니다.
보유자 토큰 인증을 사용하는 경우 계속하기 [보유자 토큰 인증 설정](CWL_HTTP_Endpoints_BearerTokenAuth.md) 전에의 설정 단계를 완료합니다.
## 요청 형식
`application/json` 만 Content-Type으로 허용됩니다.
**단일 JSON 객체:**
```
{"timestamp":1771007942000,"message":"single event","level":"INFO"}
```
**객체의 JSON 배열:**
```
[
{"timestamp":1771007942000,"message":"event one","level":"INFO"},
{"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]
```
## 허용되는 JSON 값 유형
이 엔드포인트는 엄격합니다. JSON 객체만 이벤트로 허용됩니다.
| Input | 동작 |
| --- | --- |
| 단일 JSON 객체 | 하나의 이벤트로 수락됨 |
| 객체의 JSON 배열 | 각 객체는 별도의 이벤트가 됩니다. |
| 빈 배열 [] | 수락됨, 이벤트 0개 생성 |
| 배열의 비객체(문자열, 숫자 등) | 건너뜀 |
| 최상위 프리미티브("hello", 42) | 건너뜀 |
| 연결된 객체 \$1...\$1\$1...\$1 | 첫 번째 객체만 구문 분석됨 |
**예 - 혼합 유형이 있는 배열:**
```
[
{"timestamp":1771007942000,"message":"valid object"},
"just a string",
42,
{"timestamp":1771007943000,"message":"another valid object"}
]
```
결과: 수집된 이벤트 2개(객체), 건너뛴 이벤트 2개(문자열 및 숫자).
## 타임스탬프 필드
`"timestamp"` 필드는 NDJSON 엔드포인트와 동일한 에포크 밀리초 단위입니다.
| 형식 | 예제 | 다음으로 해석됨 |
| --- | --- | --- |
| 숫자(millis) | "timestamp":1771007942000 | 1771007942000ms |
| 누락됨 | (타임스탬프 필드 없음) | 서버 현재 시간 |
| 숫자가 아닌 | "timestamp":"invalid" | 서버 현재 시간 |
## 요청 예제
```
curl -X POST "https://logs..amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
-H "Authorization: Bearer ACWL" \
-H "Content-Type: application/json" \
-d '[{"timestamp":1771007942000,"message":"User logged in","user_id":"u-123"},{"timestamp":1771007943000,"message":"Order placed","order_id":"o-456"}]'
```
## 응답
**성공(모든 이벤트 수락됨):**
```
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 명명 규칙을 따라야 합니다.
+ 보유자 토큰 인증을 사용하는 경우 로그 그룹에서 보유자 토큰 인증을 활성화해야 합니다.
## 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 형식을 수락하고 재시도 의미 체계를 사용하여 부분 성공 응답을 지원합니다.