# 使用连接日志实现可观测性
<a name="connection-logs"></a>

CloudFront 连接日志提供了双向 TLS 身份验证事件的详细信息，让您可监控证书验证、跟踪连接尝试以及解决身份验证问题。

## 什么是连接日志？
<a name="what-are-connection-logs"></a>

连接日志为已启用双向 TLS 的分配捕获有关 TLS 握手和证书验证的详细信息。与记录 HTTP 请求信息的标准访问日志不同，连接日志专注于 TLS 连接建立阶段，包括：
+ 连接状态（成功/失败）
+ 客户端证书详细信息
+ TLS 协议和密码信息
+ 连接计时指标
+ 来自连接函数的自定义数据

通过查看这些日志，您可以全面了解基于证书的身份验证事件，从而更好地监控安全性、解决问题并满足合规性要求。

## 启用连接日志
<a name="enable-connection-logs"></a>

连接日志仅适用于已启用双向 TLS 身份验证的分配。您可以将连接日志发送到多个目标，包括 CloudWatch Logs、Amazon Data Firehose 和 Amazon S3。

### 先决条件
<a name="connection-logs-prerequisites"></a>

在启用连接日志之前：
+ 为 CloudFront 分配配置双向 TLS
+ 为 CloudFront 分配启用连接日志
+ 确保您拥有所选日志记录目标所需的权限
+ 对于跨账户传输，请配置适当的 IAM 策略

### 启用连接日志（控制台）
<a name="enable-connection-logs-console"></a>

1. 登录 AWS 管理控制台，并通过以下网址打开 CloudFront 控制台：[https://console.aws.amazon.com/cloudfront/v4/home](https://console.aws.amazon.com/cloudfront/v4/home)。

1. 从分配列表中，选择已启用 mTLS 的分配。

1. 选择**日志记录**选项卡。

1. 选择**添加**。

1. 选择要接收日志的服务：
   + **CloudWatch Logs**
   + **Firehose**
   + **Amazon S3**

1. 对于**目标**，为所选服务选择资源：
   + 对于 CloudWatch Logs，输入**日志组名称**
   + 对于 Firehose，输入 **Firehose 传输流**
   + 对于 Amazon S3，输入**存储桶名称**（可选择附带前缀）

1. （可选）配置其他设置：
   + **字段选择：**选择要包含的特定日志字段。
   + **输出格式：**从 JSON、Plain、w3c、Raw 或 Parquet（仅 S3）中进行选择。
   + **字段分隔符：**指定如何分隔日志字段。

1. 选择**保存更改**

### 启用连接日志（AWS CLI）
<a name="enable-connection-logs-cli"></a>

以下示例演示如何使用 CloudWatch API 启用连接日志：

```
# Step 1: Create a delivery source
aws logs put-delivery-source \
  --name "cf-mtls-connection-logs" \
  --resource-arn "arn:aws:cloudfront::123456789012:distribution/E1A2B3C4D5E6F7" \
  --log-type CONNECTION_LOGS

# Step 2: Create a delivery destination
aws logs put-delivery-destination \
  --name "s3-destination" \
  --delivery-destination-configuration \
  "destinationResourceArn=arn:aws:s3:::amzn-s3-demo-bucket1"

# Step 3: Create the delivery
aws logs create-delivery \
  --delivery-source-name "cf-mtls-connection-logs" \
  --delivery-destination-arn "arn:aws:logs:us-east-1:123456789012:delivery-destination:s3-destination"
```

**注意**  
在使用 CloudWatch API 时，您必须指定美国东部（弗吉尼亚州北部）区域（us-east-1），即使在将日志传输到其他区域时也是如此。

## 连接日志字段
<a name="connection-log-fields"></a>

连接日志包含有关每次 TLS 连接尝试的详细信息：


| 字段 | 说明 | 示例 | 
| --- | --- | --- | 
| eventTimestamp | 连接建立成功或失败时对应的 ISO 8601 时间戳 | 1731620046814 | 
| connectionId | TLS 连接的唯一标识符 | oLHiEKbQSn8lkvJfA3D4gFowK3\$1iZ0g4i5nMUjE1Akod8TuAzn5nzg== | 
| connectionStatus |  mTLS 连接尝试的状态。  | Success 或 Failed | 
| clientIp | 连接客户端的 IP 地址 | 2001:0db8:85a3:0000:0000:8a2e:0370:7334 | 
| clientPort | 客户端使用的端口 | 12137 | 
| serverIp | CloudFront 边缘服务器的 IP 地址 | 99.84.71.136 | 
| distributionId | CloudFront 分配 ID | E2DX1SLDPK0123 | 
| distributionTenantId | CloudFront 分配租户 ID（如果适用） | dt\$12te1Ura9X3R2iCGNjW123 | 
| tlsProtocol | 使用的 TLS 协议版本 | TLSv1.3 | 
| tlsCipher | 用于连接的 TLS 密码套件 | TLS\$1AES\$1128\$1GCM\$1SHA256 | 
| tlsHandshakeDuration | TLS 握手的持续时间（毫秒） | 153 | 
| tlsSni | 来自 TLS 握手的服务器名称指示值 | d111111abcdef8.cloudfront.net | 
| clientLeafCertSerialNumber | 客户端证书的序列号 | 00:b1:43:ed:93:d2:d8:f3:9d | 
| clientLeafCertSubject | 客户端证书的主题字段 | C=US, ST=WA, L=Seattle, O=Amazon.com, OU=CloudFront, CN=client.test.mtls.net | 
| clientLeafCertIssuer | 客户端证书的颁发者字段 | C=US, ST=WA, L=Seattle, O=Amazon.com, OU=CloudFront, CN=test.mtls.net | 
| clientLeafCertValidity | 客户端证书的有效期 | NotBefore=2025-06-05T23:28:21Z;NotAfter=2125-05-12T23:28:21Z | 
| connectionLogCustomData | 通过连接函数添加的自定义数据 | REVOKED:00:b1:43:ed:93:d2:d8:f3:9d | 

## 连接错误代码
<a name="connection-error-codes"></a>

```
Failed:ClientCertMaxChainDepthExceeded
Failed:ClientCertMaxSizeExceeded
Failed:ClientCertUntrusted
Failed:ClientCertNotYetValid
Failed:ClientCertExpired
Failed:ClientCertTypeUnsupported
Failed:ClientCertInvalid
Failed:ClientCertIntentInvalid
Failed:ClientCertRejected
Failed:ClientCertMissing
Failed:TcpError
Failed:TcpTimeout
Failed:ConnectionFunctionError
Failed:ConnectionFunctionDenied
Failed:Internal
Failed:UnmappedConnectionError
```

连接失败时，CloudFront 会记录具体的原因代码：


| 代码 | 说明 | 
| --- | --- | 
| ClientCertMaxChainDepthExceeded | 已超出最大证书链深度 | 
| ClientCertMaxSizeExceeded | 已超出最大证书大小 | 
| ClientCertUntrusted | 证书不可信 | 
| ClientCertNotYetValid | 证书尚未生效 | 
| ClientCertExpired | 证书已过期 | 
| ClientCertTypeUnsupported | 证书类型不受支持 | 
| ClientCertInvalid | 证书无效 | 
| ClientCertIntentInvalid | 证书意图无效 | 
| ClientCertRejected | 证书已被自定义验证拒绝 | 
| ClientCertMissing | 证书缺失 | 
| TcpError |  尝试建立连接时出错  | 
| TcpTimeout |  无法在超时时间内建立连接  | 
| ConnectionFunctionError |  连接函数执行过程中引发了未捕获的异常  | 
| Internal |  出现内部服务错误  | 
| UnmappedConnectionError |  发生了一个无法归入任何其他类别的错误  |