本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 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"` 欄位以 epoch 秒 （非毫秒） 為單位，選用小數表示次秒精確度。


| 格式 | 範例 | 解譯為 | 
| --- | --- | --- | 
| Float | "time":1486683865.500 | 1486683865500 毫秒 | 
| Integer | "time":1486683865 | 1486683865000 毫秒 | 
| 字串 （浮點數） | "time":"1486683865.500" | 1486683865500 毫秒 | 
| 字串 （整數） | "time":"1486683865" | 1486683865000 毫秒 | 
| 缺少 | （無時間欄位） | 伺服器目前時間 | 
| 無效 | "time":"invalid" | 伺服器目前時間 | 

## 內容類型
<a name="CWL_HLC_Content_Type"></a>

僅接受 `application/json` 。

## 接受的 JSON 值類型
<a name="CWL_HLC_Accepted_Types"></a>


| 最上層類型 | Behavior (行為) | 
| --- | --- | 
| 具有 的物件 "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 Region （例如，`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 時間戳記，選用小數表示次秒精確度 （選用）
+ `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–100 個事件
+ 請求大小上限：1 MB

### 錯誤處理
<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>
+ 事件大小上限：每個事件 256 KB
+ 請求大小上限：1 MB
+ 每個請求的事件上限：10，000
+ 日誌群組名稱必須遵循 CloudWatch Logs 命名慣例
+ 如果使用承載字符身分驗證，則必須在日誌群組上啟用承載字符身分驗證。