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

# 通过 HTTP 端点记录摄取
通过 HTTP 端点记录摄取

Amazon CloudWatch Logs 提供了 HTTP 终端节点，允许您使用简单的 HTTP POST 请求将 CloudWatch 日志直接发送到日志。这些端点支持 Sigv4 和持有者令牌身份验证。

**重要**  
我们建议对所有可以集成 S Amazon DK 的生产工作负载使用 Sigv4 身份验证。Sigv4 使用短期凭证并提供最强的安全状态。不记名令牌（API 密钥）身份验证适用于 Sigv4 不可行的场景，例如不支持 SDK 集成的第三方日志转发器。 Amazon 有关更多信息，请参阅 *IAM 用户指南*中的[长期访问密钥替代方案](https://docs.amazonaws.cn/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)。

CloudWatch 日志支持以下 HTTP 摄取终端节点：


| 端点 | 路径 | Content-Type | Format | 
| --- | --- | --- | --- | 
| [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 摄取端点都具有以下行为：

**身份验证**

所有端点都支持 Sigv4 和持有者令牌身份验证：
+ **Sigv4（推荐）**— 标准 Amazon 签名版本 4 签名。只要您的应用程序或基础设施支持 S Amazon DK 或可以签署请求，就使用 Sigv4。Sigv4 使用短期凭证，是最安全的身份验证方法。
+ **不记名令牌**-使用`Authorization: Bearer <ACWL token>`标题。
  + 令牌必须是有效的 ACWL 持有者令牌。有关设置说明，请参阅[设置不记名令牌身份验证](CWL_HTTP_Endpoints_BearerTokenAuth.md)。
  + 需要`logs:PutLogEvents`和 `logs:CallWithBearerToken` IAM 权限。

**日志组和日志流**
+ 通过标题提供：`x-aws-log-group`和 `x-aws-log-stream`
+ 除了 OTLP 之外，所有端点也`?logGroup=<name>&logStream=<name>`都支持查询参数。
+ 不能对同一个参数同时使用查询参数和标头。
+ 日志组和日志流都是必需的。

**响应**
+ 成功：`HTTP 200`用身体 `{}`
+ 验证错误：`HTTP 400`
+ 身份验证失败：`HTTP 401`

# 设置不记名令牌身份验证
不记名令牌认证

在使用持有者令牌身份验证向任何 HTTP 摄取端点发送日志之前，您需要：
+ 创建具有 CloudWatch 日志权限的 IAM 用户
+ 生成特定于服务的凭证（持有者令牌）
+ 创建日志组和日志流
+ 在日志组上启用不记名令牌身份验证

**重要**  
我们建议在可能的情况下对所有工作负载使用带有短期凭证的 Sigv4 身份验证。SigV4 提供了最强的安全态势。将 API 密钥（不记名令牌）的使用限制在基于凭证的短期身份验证不可行的场景中。当您准备好将 CloudWatch 日志整合到具有更高安全要求的应用程序中时，应切换到短期凭证。有关更多信息，请参阅 *IAM 用户指南*中的[长期访问密钥替代方案](https://docs.amazonaws.cn/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)。

## 选项 1：使用 Amazon 控制台快速入门


 Amazon 管理控制台简化了生成用于 HTTP 端点访问的 API 密钥的工作流程。

**使用控制台设置 HTTP 端点访问权限**

1. 登录到 Amazon 管理控制台。

1. 导航至 **CloudWatch**> **设置** > **日志**。

1. 在 API 密钥部分中，选择**生成 API 密钥**。

1. 对于 **API 密钥过期时间**，请执行以下操作之一：
   + 将 API 密钥的过期时间选择为 **1**、**5**、**30**、**90** 或 **365** 天。
   + 选择**自定义持续时间**以指定自定义 API 密钥到期日期。
   + 选择**永不过期**（不推荐）。

1. 选择**生成 API 密钥**。

   控制台自动：
   + 创建具有适当权限的新 IAM 用户
   + 附加[CloudWatchLogsAPIKey访问](https://docs.amazonaws.cn/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:CallWithBearerToken`— 使用不记名令牌进行身份验证
+ `kms:Describe*`,`kms:GenerateDataKey*`, `kms:Decrypt` — 访问 KMS 加密的日志组（条件仅限于日志服务）

## 选项 2：手动设置


如果您希望更好地控制 IAM 配置或需要自定义权限，则可以手动设置 HTTP 终端节点访问权限。

### 步骤 1：创建 IAM 用户


创建将用于日志提取的 IAM 用户：

1. 登录 Amazon 管理控制台并导航到 IAM。

1. 在左侧导航窗格中，选择 **用户**。

1. 选择**创建用户**。

1. 输入用户名（例如，`cloudwatch-logs-hlc-user`）。

1. 选择**下一步**。

1. 附上以下 IAM 策略之一：

   **选项 A：使用托管策略（推荐）**

   附加[CloudWatchLogsAPIKey访问](https://docs.amazonaws.cn/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 日志服务使用的密钥。

### 步骤 2：生成特定于服务的凭证（API 密钥）


使用 API 生成 CloudWatch 日志 AP [CreateServiceSpecificCredential](https://docs.amazonaws.cn/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html)I 密钥。您也可以使用 [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html)CLI 命令。对于凭证期限，您可以指定一个介于 1-36600 天之间的值。如果未指定凭证期限，则 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.amazonaws.cn/IAM/latest/APIReference/API_ServiceSpecificCredential.html)对象。`ServiceCredentialSecret`值是您的 CloudWatch 日志 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 日志 API 密钥的权限


 CloudWatch 日志 API 密钥的生成和使用由 CloudWatch 日志和 IAM 服务中的操作和条件密钥控制。

### 控制日 CloudWatch 志 API 密钥的生成


i [am: CreateServiceSpecificCredential](https://docs.amazonaws.cn/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) 操作控制特定于服务的密钥（例如 CloudWatch 日志 API 密钥）的生成。您可以将此操作作为一种资源，将操作范围限定为 IAM 用户，以便限制可以为其生成密钥的用户。

您可以使用以下条件密钥对 `iam:CreateServiceSpecificCredential` 操作的权限施加条件：
+ [iam: ServiceSpecificCredentialAgeDays](https://docs.amazonaws.cn/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — 允许您在条件中指定密钥的到期时间（以天为单位）。例如，您可以使用此条件密钥仅允许创建将在 90 天内过期的 API 密钥。
+ [iam: ServiceSpecificCredentialServiceName](https://docs.amazonaws.cn/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — 允许您在条件中指定服务的名称。例如，您可以使用此条件密钥仅允许为 CloudWatch 日志创建 API 密钥，而不允许为其他服务创建 API 密钥。

### 控制日 CloudWatch 志 API 密钥的使用


该`logs:CallWithBearerToken`操作控制 CloudWatch 日志 API 密钥的使用。要防止身份使用 L CloudWatch ogs API 密钥，请向与该密钥关联的 IAM 用户附加拒绝该`logs:CallWithBearerToken`操作的策略。

### 策略示例


#### 阻止身份生成和使用 CloudWatch 日志 API 密钥


```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "DenyCWLAPIKeys",
            "Effect": "Deny",
            "Action": [
                "iam:CreateServiceSpecificCredential",
                "logs:CallWithBearerToken"
            ],
            "Resource": "*"
        }
    ]
}
```

**警告**  
此策略将禁止为所有支持创建特定 Amazon 服务凭证的服务创建凭证。有关更多信息，请参阅 [IAM 用户的服务特定凭证](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_service-specific-creds.html)。

#### 阻止身份使用日 CloudWatch 志 API 密钥


```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "logs:CallWithBearerToken",
            "Resource": "*"
        }
    ]
}
```

#### 仅当 CloudWatch 日志密钥在 90 天内过期时，才允许创建这些密钥


```
{
    "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. （可选）存储新凭证， Amazon 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. 监控中日志组的`IncomingBytes`指标，确认日志传输不会受到影响 CloudWatch。有关更多信息，请参阅[使用 CloudWatch 指标进行监控](https://docs.amazonaws.cn/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](#CWL_HTTP_Endpoints_CloudTrail_Logging)有关如何启用 API 密钥使用情况审计，请参阅。

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 执行这些操作，您必须使用 Amazon 凭据进行身份验证，而不是使用 CloudWatch 日志 API 密钥进行身份验证。

您还可以使用以下 IAM API 操作来管理泄露的密钥：
+ [ResetServiceSpecificCredential](https://docs.amazonaws.cn/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html)— 在不删除凭据的情况下重置密钥以生成新密码。密钥必须未过期。

## API 密钥的安全最佳实践


请遵循以下最佳做法来保护您的 CloudWatch 日志 API 密钥：
+ **切勿在源代码中嵌入 API 密钥。**请勿在应用程序代码中对 API 密钥进行硬编码，也不要将其提交到版本控制系统。如果密钥意外被提交到公共存储库，则 Amazon 自动扫描可能会对其进行标记，因此您应立即轮换密钥。
+ **使用密钥管理器。**将 API 密钥存储在[Amazon Secrets Manager](https://docs.amazonaws.cn/secretsmanager/latest/userguide/intro.html)或等效的机密管理解决方案中。这可以实现集中访问控制、审核日志和自动轮换。
+ **为所有密钥设置过期时间。**创建 API 密钥时，请务必指定一个`--credential-age-days`值。要在整个组织中强制使用最长密钥生命周期，请使用 `iam:ServiceSpecificCredentialAgeDays` IAM 条件密钥。有关示例，请参阅[仅当 CloudWatch 日志密钥在 90 天内过期时，才允许创建这些密钥](#CWL_HTTP_Endpoints_Allow_Expire_90)。
+ **应用最低权限权限。**将 IAM 用户的权限范围仅限于所需的日志组和操作。使用托管[CloudWatchLogsAPIKey访问](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html)策略作为起点，并根据需要进一步限制。
+ **启用 CloudTrail 日志记录。**通过为启用 CloudTrail 数据事件来审计 API 密钥使用情况`AWS::Logs::LogGroupAuthorization`。请参阅[使用记录 API 密钥的使用情况 CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging)。
+ **使用 IAM 访问分析器进行监控。**使用 [IAM Access Analyzer](https://docs.amazonaws.cn/IAM/latest/UserGuide/what-is-access-analyzer.html) 来识别与您的 API 密钥 IAM 用户关联的未使用证书和过于宽松的策略。
+ **定期轮换密钥。**制定轮换时间表并按照中所述的流程进行操作[轮换 API 密钥](#CWL_HTTP_Endpoints_Rotating_Keys)。

## 使用记录 API 密钥的使用情况 CloudTrail


您可以使用 Amazon CloudTrail 记录日 CloudWatch 志 API 密钥使用情况的数据事件。 CloudWatch 日志会发出`CallWithBearerToken`呼叫`AWS::Logs::LogGroupAuthorization`的数据事件，使您能够审计 API 密钥何时以及如何用于发送日志。

要启用 CloudTrail 日志记录 API 密钥使用情况，请执行以下操作： CloudWatch 

**注意**  
您为跟踪指定的 S3 存储桶必须具有允许 CloudTrail 向其写入日志文件的存储桶策略。有关更多信息，请参阅 [Amazon S3 存储桶政策 CloudTrail](https://docs.amazonaws.cn/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 日志日志组授权事件：

   ```
   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 日志（日志）
OTLP 端点

 OpenTelemetry 日志端点 (`/v1/logs`) 接受 JSON 或 Protobuf 编码的 OpenTelemetry 协议 (OTLP) 日志数据。有关 OTLP 端点的详细信息，包括配置和使用情况，请参阅使用[发送指标和 CloudWatch 跟 OpenTelemetry踪](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)。

如果您使用的是不记名令牌身份验证，请先完成中的设置步骤，[设置不记名令牌身份验证](CWL_HTTP_Endpoints_BearerTokenAuth.md)然后再继续。

## 请求格式

+ 方法：`POST`
+ 内容类型：或 `application/json` `application/x-protobuf`
+ 日志组：仅限`x-aws-log-group`标题（不支持查询参数）
+ 日志流：`x-aws-log-stream`标头

## 示例请求


```
curl -X POST "https://logs.<region>.amazonaws.com/v1/logs" \
  -H "Authorization: Bearer ACWL<token>" \
  -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 终端节点

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 日志命名约定
+ 如果使用不记名令牌身份验证，则必须在日志组上启用持有者令牌身份验证。

# 使用 NDJSON 端点发送日志（ND-JSON 日志）
ndjson 端点

ND-JSON 日志端点 (`/ingest/bulk`) 接受 [NDJSON（换行符分隔 JSON](https://github.com/ndjson/ndjson-spec)）格式的日志。每行只包含一个 JSON 值，由换行符分隔。

如果您使用的是不记名令牌身份验证，请先完成中的设置步骤，[设置不记名令牌身份验证](CWL_HTTP_Endpoints_BearerTokenAuth.md)然后再继续。

## 请求格式


每行发送一个 JSON 值，以 `\n` (LF) 或 `\r\n` (CRLF) 分隔。空行会被静默忽略。

```
{"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`都被接受为内容类型。

## 接受的 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 空 | 已接受为活动消息 | 
| JSON 无效 | 已跳过（已计数，处理仍在继续） | 
| 空行 | 已忽略（未计为已跳过） | 

## 时间戳字段


该`"timestamp"`字段以纪元毫秒（不是秒）为单位。


| 格式 | 示例 | 解释为 | 
| --- | --- | --- | 
| 数字（毫秒） | "timestamp":1771007942000 | 1771007942000 ms | 
| 缺失 | （没有时间戳字段） | 服务器当前时间 | 
| 非数字 | "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.<region>.amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -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—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 日志命名约定
+ 如果使用不记名令牌身份验证，则必须在日志组上启用持有者令牌身份验证。

# 使用结构化 JSON 端点发送日志（结构化 JSON 日志）
结构 JSON 端点

结构化 JSON 日志端点 (`/ingest/json`) 接受标准 JSON，可以是单个 JSON 对象，也可以是对象的 JSON 数组。此端点专为结构化日志数据而设计，其中每个事件都是一个 JSON 对象。

如果您使用的是不记名令牌身份验证，请先完成中的设置步骤，[设置不记名令牌身份验证](CWL_HTTP_Endpoints_BearerTokenAuth.md)然后再继续。

## 请求格式


仅`application/json`被接受为内容类型。

**单个 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 个事件 | 
| 数组中的非对象（字符串、数字等） | Skipped | 
| 顶级原语 ("hello",42) | Skipped | 
| 连接的对象 \$1...\$1\$1...\$1 | 仅解析第一个对象 | 

**示例 — 混合类型的数组：**

```
[
  {"timestamp":1771007942000,"message":"valid object"},
  "just a string",
  42,
  {"timestamp":1771007943000,"message":"another valid object"}
]
```

结果：提取了 2 个事件（对象），跳过 2 个事件（字符串和数字）。

## 时间戳字段


该`"timestamp"`字段以纪元毫秒为单位，与 NDJSON 端点相同。


| 格式 | 示例 | 解释为 | 
| --- | --- | --- | 
| 数字（毫秒） | "timestamp":1771007942000 | 1771007942000 ms | 
| 缺失 | （没有时间戳字段） | 服务器当前时间 | 
| 非数字 | "timestamp":"invalid" | 服务器当前时间 | 

## 示例请求


```
curl -X POST "https://logs.<region>.amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -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—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 日志命名约定
+ 如果使用不记名令牌身份验证，则必须在日志组上启用持有者令牌身份验证。

## 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 日志。接受 OTLP JSON 或 Protobuf 格式，并支持带有重试语义的部分成功响应。