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

# 使用連線日誌的可觀測性
<a name="connection-logs"></a>

CloudFront 連線日誌提供交互 TLS 身分驗證事件的詳細可見性，可讓您監控憑證驗證、追蹤連線嘗試，以及疑難排解身分驗證問題。

## 什麼是連線日誌？
<a name="what-are-connection-logs"></a>

連線日誌會擷取有關啟用交互 TLS 分佈的 TLS 交握和憑證驗證的詳細資訊。與記錄 HTTP 請求資訊的標準存取日誌不同，連線日誌特別著重於 TLS 連線建立階段，包括：
+ 連線狀態 （成功/失敗）
+ 用戶端憑證詳細資訊
+ TLS 通訊協定和密碼資訊
+ 連線時間指標
+ 來自 Connection Functions 的自訂資料

這些日誌提供憑證型身分驗證事件的全方位可見性，協助您監控安全性、疑難排解問題，並符合合規要求。

## 啟用連線日誌
<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. 選擇 **Logging** (日誌記錄) 索引標籤。

1. 選擇**新增**。

1. 選取要接收日誌的服務：
   + **CloudWatch Logs**
   + **Firehose**
   + **Amazon S3**

1. 針對**目的地**，選取所選服務的資源：
   + 針對 CloudWatch Logs，輸入**日誌群組名稱**
   + 對於 Firehose，選取 **Firehose 交付串流**
   + 對於 Amazon S3，輸入**儲存貯體名稱** （選擇性使用字首）

1. (選用) 設定其他設定：
   + **欄位選擇：**選取要包含的特定日誌欄位。
   + **輸出格式：**從 JSON、Plain、w3c、Raw 或 Parquet （僅限 S3) 中選擇。
   + **欄位分隔符號：**指定如何分隔日誌欄位。

1. 選擇 **Save changes (儲存變更)**

### 啟用連線日誌 (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 連線嘗試的詳細資訊：


| 欄位 | Description | 範例 | 
| --- | --- | --- | 
| 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 | 透過 Connection Functions 新增的自訂資料 | 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 會記錄特定原因代碼：


| Code | Description | 
| --- | --- | 
| ClientCertMaxChainDepthExceeded | 超過憑證鏈深度上限 | 
| ClientCertMaxSizeExceeded | 超過憑證大小上限 | 
| ClientCertUntrusted | 憑證不受信任 | 
| ClientCertNotYetValid | 憑證尚無效 | 
| ClientCertExpired | 憑證已過期 | 
| ClientCertTypeUnsupported | 不支援憑證類型 | 
| ClientCertInvalid | 憑證無效 | 
| ClientCertIntentInvalid | 憑證意圖無效 | 
| ClientCertRejected | 自訂驗證拒絕的憑證 | 
| ClientCertMissing | 憑證遺失 | 
| TcpError |  嘗試建立連線時發生錯誤  | 
| TcpTimeout |  無法在逾時期間內建立連線  | 
| ConnectionFunctionError |  在 Connection Function 執行期間擲回未攔截的例外狀況  | 
| 內部 (Internal) |  發生內部服務錯誤  | 
| UnmappedConnectionError |  發生錯誤，該錯誤不屬於任何其他類別  |