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

# HLC 엔드포인트를 사용하여 로그 전송(HLC 로그)
<a name="CWL_HLC_Endpoint"></a>

HLC Logs 엔드포인트(`/services/collector/event`)는 HTTP Log Collector(HLC) 형식을 기반으로 합니다.

보유자 토큰 인증을 사용하는 경우 계속하기 [보유자 토큰 인증 설정](CWL_HTTP_Endpoints_BearerTokenAuth.md) 전에의 설정 단계를 완료합니다.

## 입력 모드
<a name="CWL_HLC_Input_Modes"></a>

각 이벤트는 필수 `"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}
```

## 이벤트 필드(필수)
<a name="CWL_HLC_Event_Field"></a>

`"event"` 필드는 필수입니다. 값은 모든 JSON 유형일 수 있습니다.

```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```

`"event"` 필드가 없는 객체는 자동으로 건너뜁니다.

```
{"message":"this is skipped — no event field"}
```

## 시간 필드(선택 사항)
<a name="CWL_HLC_Time_Field"></a>

`"time"` 필드는 에포크 초(밀리초 아님) 단위이며, 10진수는 1초 미만의 정밀도에 대한 선택적 10진수입니다.


| 형식 | 예제 | 다음으로 해석됨 | 
| --- | --- | --- | 
| Float | "time":1486683865.500 | 1486683865500ms | 
| Integer | "time":1486683865 | 1486683865000ms | 
| 문자열(부동 소수점) | "time":"1486683865.500" | 1486683865500ms | 
| 문자열(정수) | "time":"1486683865" | 1486683865000ms | 
| 누락됨 | (시간 필드 없음) | 서버 현재 시간 | 
| 잘못됨 | "time":"invalid" | 서버 현재 시간 | 

## Content-Type
<a name="CWL_HLC_Content_Type"></a>

만 `application/json` 허용됩니다.

## 허용되는 JSON 값 유형
<a name="CWL_HLC_Accepted_Types"></a>


| 최상위 유형 | 동작 | 
| --- | --- | 
| 가 있는 객체 "event" | 수락됨 | 
| 가 없는 객체 "event" | 건너뜀 | 
| 객체 배열 | 개별적으로 처리되는 각 요소 | 
| 연결된 객체 | 개별적으로 처리되는 각 객체 | 
| 프리미티브(문자열, 숫자, 부울, null) | 건너뜀 | 

## 엔드포인트 형식
<a name="CWL_HLC_Endpoint_Format"></a>

HLC 엔드포인트 URL은 다음 형식을 따릅니다.

```
https://logs.<region>.amazonaws.com/services/collector/event?logGroup=<name>&logStream=<name>[&entityName=<name>&entityEnvironment=<environment>]
```

**필수 파라미터:**
+ `<region>` – 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`)로 저장됩니다.

## 요청 형식
<a name="CWL_HLC_Request_Format"></a>

다음 헤더 및 본문과 함께 HTTP POST를 사용하여 로그를 전송합니다.

**헤더:**
+ `Authorization: Bearer <your-bearer-token>`
+ `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` - 로그 소스 식별자(선택 사항)

필요에 따라 추가 사용자 지정 필드를 포함할 수 있습니다.

## 요청 예제
<a name="CWL_HLC_Example_Request"></a>

```
curl -X POST "https://logs.<region>.amazonaws.com/services/collector/event?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -H "Content-Type: application/json" \
  -d '{"event":{"message":"User logged in","user_id":"u-123"},"time":1486683865.0,"host":"web-01","source":"auth-service"}'
```

## 모범 사례
<a name="CWL_HLC_Best_Practices"></a>

### 이벤트 일괄 처리
<a name="CWL_HLC_Batching"></a>

성능 및 효율성 향상을 위해:
+ 가능한 경우 단일 요청으로 여러 이벤트 배치
+ 권장 배치 크기: 요청당 이벤트 10\$1100개
+ 최대 요청 크기: 1MB

### 오류 처리
<a name="CWL_HLC_Error_Handling"></a>

애플리케이션에서 적절한 오류 처리를 구현합니다. 일반적인 HTTP 상태 코드:
+ `200 OK` - 로그가 성공적으로 수집됨
+ `400 Bad Request` - 잘못된 요청 형식 또는 파라미터
+ `401 Unauthorized` - 유효하지 않거나 만료된 보유자 토큰
+ `403 Forbidden` - 권한 부족
+ `404 Not Found` - 로그 그룹 또는 스트림이 존재하지 않음
+ `429 Too Many Requests` - 속도 제한 초과
+ `500 Internal Server Error` - 서비스 오류(지수 백오프로 재시도)

## 제한 사항
<a name="CWL_HLC_Limitations"></a>
+ 최대 이벤트 크기: 이벤트당 256KB
+ 최대 요청 크기: 1MB
+ 요청당 최대 이벤트 수: 10,000
+ 로그 그룹 이름은 CloudWatch Logs 명명 규칙을 따라야 합니다.
+ 보유자 토큰 인증을 사용하는 경우 로그 그룹에서 보유자 토큰 인증을 활성화해야 합니다.