本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 HLC 端点发送日志（HLC 日志）
HLC 终端节点

HLC 日志端点 (`/services/collector/event`) 基于 HTTP 日志收集器 (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"`字段以纪元秒（不是毫秒）为单位，可选小数表示亚秒精度。


| 格式 | 示例 | 解释为 | 
| --- | --- | --- | 
| 浮点型 | "time":1486683865.500 | 1486683865500 毫秒 | 
| 整数 | "time":1486683865 | 1486683865000 毫秒 | 
| 字符串（浮点数） | "time":"1486683865.500" | 1486683865500 毫秒 | 
| 字符串（整数） | "time":"1486683865" | 1486683865000 毫秒 | 
| 缺失 | （无时间字段） | 服务器当前时间 | 
| 无效 | "time":"invalid" | 服务器当前时间 | 

## Content-Type


只`application/json`被接受。

## 接受的 JSON 值类型



| 顶级类型 | 行为 | 
| --- | --- | 
| 带的对象 "event" | 已接受 | 
| 没有的物体 "event" | Skipped | 
| 对象数组 | 每个元素都单独处理 | 
| 连接的对象 | 每个对象都单独处理 | 
| 基元（字符串、数字、布尔值、空） | Skipped | 

## 终端节点格式


HLC 端点 URL 遵循以下格式：

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

**必填参数：**
+ `<region>`— Amazon 区域（例如，`us-east-1`、`eu-west-1`）
+ `logGroup`— URL 编码的日志组名称
+ `logStream`— URL 编码的日志流名称

**可选参数：**

您可以选择通过添加以下查询参数将日志事件与`Service`实体相关联。由于通过 HLC 端点发送的日志是自定义遥测数据，因此它们不会自动与实体关联。通过提供这些参数， CloudWatch Logs 会创建一个`KeyAttributes.Type`设置为`Service`的实体，并将其与您的日志事件相关联。这使中与 Explore **相关的**功能可以 CloudWatch 将这些日志与来自同一服务的其他遥测（指标、跟踪和日志）关联起来，从而更轻松地对不同信号类型的应用程序进行故障排除和监控。有关实体和相关遥测的更多信息，请参阅[向自定义遥测添加相关信息](https://docs.amazonaws.cn/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 <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 纪元时间戳（以秒为单位），可选十进制表示亚秒精度（可选）
+ `event`— 日志消息或事件数据（必填）
+ `host`— 源主机名或标识符（可选）
+ `source`— 日志源标识符（可选）

可以根据需要添加其他自定义字段。

## 示例请求


```
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"}'
```

## 最佳实践


### 对事件进行批处理


为了获得更好的性能和效率：
+ 尽可能在单个请求中批量处理多个事件
+ 建议的批处理大小：每个请求 10—100 个事件
+ 最大请求大小：1 MB

### 错误处理


在应用程序中实现正确的错误处理。常见的 HTTP 状态码：
+ `200 OK`— 已成功提取日志
+ `400 Bad Request`— 请求格式或参数无效
+ `401 Unauthorized`— 不记名令牌无效或已过期
+ `403 Forbidden`— 权限不足
+ `404 Not Found`— 日志组或直播不存在
+ `429 Too Many Requests`— 超出速率限制
+ `500 Internal Server Error`— 服务错误（使用指数退避重试）

## 限制

+ 最大事件大小：每个事件 256 KB
+ 最大请求大小：1 MB
+ 每个请求的最大事件数：10,000
+ 日志组名称必须遵循 CloudWatch 日志命名约定
+ 如果使用不记名令牌身份验证，则必须在日志组上启用持有者令牌身份验证。