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

# Amazon MSK Replicator 疑難排解
<a name="msk-replicator-troubleshooting"></a>

以下資訊可協助您疑難排解 MSK Replicator 的問題。如需其他 Amazon MSK 功能[對 Amazon MSK 叢集進行故障診斷](troubleshooting.md)，請參閱 。您也可以將您的問題張貼到 [AWS re:Post](https://repost.aws/)。

## 複寫器狀態從 CREATING 變為 FAILED
<a name="msk-replicator-ts-failed-state"></a>

MSK Replicator 建立失敗的常見原因：

1. 確認您為目標叢集提供的安全群組具有傳出規則，以允許流量流向目標叢集的安全群組，且目標叢集的安全群組具有接受來自複寫器安全群組流量的傳入規則。

1. 對於跨區域複寫，確認您的來源叢集已針對 IAM 存取控制開啟多 VPC 連線，且已在來源叢集上設定叢集政策。

1. 確認建立期間提供的 IAM 角色具有讀取和寫入來源和目標叢集所需的許可，包括寫入主題的許可。

1. 確認您的網路 ACLs 未封鎖 MSK Replicator 與叢集之間的連線。

1. 當 MSK Replicator 嘗試連線時，來源或目標叢集可能無法完全可用。這可能是因為負載過大、磁碟用量或 CPU 用量過大所致。修復代理程式的問題，然後重試建立複寫器。

執行上述驗證後，請再次建立 MSK Replicator。

## 複寫器似乎卡在 CREATING 狀態
<a name="msk-replicator-ts-stuck-creating"></a>

MSK Replicator 建立最多可能需要 30 分鐘。等候 30 分鐘，然後再次檢查複寫器的狀態。

## 複寫器不會複寫資料或僅複寫部分資料
<a name="msk-replicator-ts-not-replicating"></a>

1. 使用 Amazon CloudWatch 中的 `AuthError` 指標，確認您的複寫器未執行身分驗證錯誤。如果此指標高於 0，請檢查 IAM 角色政策，並確保叢集許可沒有設定拒絕許可。

1. 確認您的來源和目標叢集沒有遇到問題 （連線過多、磁碟容量不足或 CPU 用量過高）。

1. 使用 `KafkaClusterPingSuccessCount` 指標確認您的叢集可以連線。如果此指標為 0 或沒有資料點，請檢查網路和 IAM 角色許可。

1. 使用 `ReplicatorFailure`指標確認您的複寫器未執行失敗。如果超過 0，請檢查 IAM 角色是否有主題層級許可。

1. 確認允許清單中的規則表達式符合您要複寫的主題名稱，而且拒絕清單不會排除該主題。

1. 複寫器最多可能需要 30 秒才能偵測和建立新主題。如果在目標叢集上建立主題之前產生的訊息，如果開始位置是*最新的* （預設），則不會複寫。

## 目標叢集中的訊息位移與來源叢集不同
<a name="msk-replicator-ts-offset-mismatch"></a>

MSK Replicator 會使用來源叢集的訊息，並將訊息產生到目標叢集，這可能會導致不同的位移。如果您已開啟取用者群組位移同步，MSK Replicator 會自動翻譯位移，以便在容錯移轉之後，您的取用者可以從停止的附近繼續處理。

## 複寫器未同步取用者群組位移
<a name="msk-replicator-ts-consumer-groups"></a>

1. 驗證資料複寫是否如預期般運作。

1. 確認允許清單中的規則表達式符合您要複寫的取用者群組。

1. 確認 MSK Replicator 已在目標叢集上建立主題。如果您在來源叢集上的取用者群組只使用了尚未複寫的訊息，則取用者群組將不會複寫到目標叢集。一旦您的取用者群組開始讀取新複寫的訊息，MSK Replicator 將自動複寫取用者群組。

**注意**  
MSK Replicator 會針對從主題分割區接近結尾處讀取的消費者，最佳化消費者群組位移同步。如果您的取用者群組在來源叢集上延遲，您可能會在目標上看到較高的延遲。隨著您的消費者追上進度，MSK Replicator 會自動減少延遲。

## 複寫延遲很高或持續增加
<a name="msk-replicator-ts-high-latency"></a>

1. 確認您有正確數量的分割區。下表顯示您所需輸送量的建議最小分割區數量。  
**輸送量和建議的分區數量下限**    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/msk/latest/developerguide/msk-replicator-troubleshooting.html)

1. 確認叢集中有足夠的讀取和寫入容量。MSK Replicator 可作為來源叢集 (輸出) 的取用者，以及作為目標叢集 (輸入) 的生產者。除了其他流量之外，佈建叢集容量以支援複寫流量。

1. 複寫延遲因區域配對距離而異。

1. 確認您的複寫器並未使用 `ThrottleTime` 指標進行調節。如果超過 0，請調整 Kafka 配額。請參閱 [使用 Kafka 配額管理輸送量](msk-replicator-bp-quotas.md)。

1. 檢查您區域中 MSK 服務事件[AWS 的服務運作狀態儀表板](https://health.aws.amazon.com/health/status)。

## 使用 ReplicatorFailure 指標進行故障診斷
<a name="msk-replicator-ts-replicator-failure"></a>

`ReplicatorFailure` 指標可協助您監控和偵測複寫問題。非零值通常表示由於訊息大小限制、時間戳記範圍違規或記錄批次大小問題而導致的複寫失敗。如果您已為複寫器設定日誌交付，您可以使用交付的日誌訊息來識別特定失敗。如需詳細資訊，請參閱[MSK Replicator 日誌](msk-replicator-logs.md)。如果未設定日誌交付，請依照下列步驟查詢複寫器的狀態主題是否有錯誤訊息。

如果`ReplicatorFailure`指標報告非零值，請依照下列步驟進行疑難排解：

1. 設定可連線至目標 MSK 叢集且已設定 Apache Kafka CLI 工具的用戶端。請參閱 [連線至 Amazon MSK 佈建叢集](client-access.md)。

1. 開啟 Amazon MSK 主控台，網址為 [https://console.aws.amazon.com/msk/home?region=us-east-1\#/home/](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)。

   取得 MSK Replicator 和目標 MSK 叢集ARNs，並[取得目標 MSK 叢集的代理程式端點](get-bootstrap-console.md)。

1. 匯出 MSK Replicator ARN 和代理程式端點：

   ```
   export TARGET_CLUSTER_SERVER_STRING=<BootstrapServerString>
   export REPLICATOR_ARN=<ReplicatorARN>
   export CONSUMER_CONFIG_FILE=<ConsumerConfigFile>
   ```

1. 在您的 `<path-to-your-kafka-installation>/bin`目錄中，將下列指令碼儲存為 **query-replicator-failure-message.sh**。

   ```
   #!/bin/bash
   
   # Script: Query MSK Replicator Failure Message
   # Description: This script queries exceptions from AWS MSK Replicator status topics
   # It takes a replicator ARN and bootstrap server as input and searches for replicator exceptions
   # in the replicator's status topic, formatting and displaying them in a readable manner
   #
   # Required Arguments:
   #   --replicator-arn: The ARN of the AWS MSK Replicator
   #   --bootstrap-server: The Kafka bootstrap server to connect to
   #   --consumer.config: Consumer config properties file
   # Usage Example:
   #   ./query-replicator-failure-message.sh --replicator-arn <replicator-arn> --bootstrap-server <bootstrap-server> --consumer.config <consumer.config>
   
   print_usage() {
     echo "USAGE: $0 ./query-replicator-failure-message.sh --replicator-arn <replicator-arn> --bootstrap-server <bootstrap-server> --consumer.config <consumer.config>"
     echo "--replicator-arn <String: MSK Replicator ARN>      REQUIRED: The ARN of AWS MSK Replicator."
     echo "--bootstrap-server <String: server to connect to>  REQUIRED: The Kafka server to connect to."
     echo "--consumer.config <String: config file>            REQUIRED: Consumer config properties file."
     exit 1
   }
   
   # Initialize variables
   replicator_arn=""
   bootstrap_server=""
   consumer_config=""
   
   # Parse arguments
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --replicator-arn)
         if [ -z "$2" ]; then
           echo "Error: --replicator-arn requires an argument."
           print_usage
         fi
         replicator_arn="$2"; shift 2 ;;
       --bootstrap-server)
         if [ -z "$2" ]; then
           echo "Error: --bootstrap-server requires an argument."
           print_usage
         fi
         bootstrap_server="$2"; shift 2 ;;
       --consumer.config)
         if [ -z "$2" ]; then
           echo "Error: --consumer.config requires an argument."
           print_usage
         fi
         consumer_config="$2"; shift 2 ;;
       *) echo "Unknown option: $1"; print_usage ;;
     esac
   done
   
   # Check for required arguments
   if [ -z "$replicator_arn" ] || [ -z "$bootstrap_server" ] || [ -z "$consumer_config" ]; then
     echo "Error: --replicator-arn, --bootstrap-server, and --consumer.config are required."
     print_usage
   fi
   
   # Extract replicator name and suffix from ARN
   replicator_arn_suffix=$(echo "$replicator_arn" | awk -F'/' '{print $NF}')
   replicator_name=$(echo "$replicator_arn" | awk -F'/' '{print $(NF-1)}')
   echo "Replicator name: $replicator_name"
   
   # List topics and find the status topic
   topics=$(./kafka-topics.sh --command-config client.properties --list --bootstrap-server "$bootstrap_server")
   status_topic_name="__amazon_msk_replicator_status_${replicator_name}_${replicator_arn_suffix}"
   
   # Check if the status topic exists
   if echo "$topics" | grep -Fq "$status_topic_name"; then
     echo "Found replicator status topic: '$status_topic_name'"
     ./kafka-console-consumer.sh --bootstrap-server "$bootstrap_server" --consumer.config "$consumer_config" --topic "$status_topic_name" --from-beginning | stdbuf -oL grep "Exception" | stdbuf -oL sed -n 's/.*Exception:\(.*\) Topic: \([^,]*\), Partition: \([^\]*\).*/ReplicatorException:\1 Topic: \2, Partition: \3/p'
   else
     echo "No topic matching the pattern '$status_topic_name' found."
   fi
   ```

   執行此指令碼來查詢 MSK Replicator 失敗訊息：

   ```
   <path-to-your-kafka-installation>/bin/query-replicator-failure-message.sh --replicator-arn $REPLICATOR_ARN --bootstrap-server $TARGET_CLUSTER_SERVER_STRING --consumer.config $CONSUMER_CONFIG_FILE
   ```

   此指令碼會輸出所有錯誤及其例外狀況訊息和受影響的主題分割區。由於主題包含所有歷史故障訊息，請使用最後一個訊息開始調查。以下是失敗訊息的範例：

   ```
   ReplicatorException: The request included a message larger than the max message size the server will accept. Topic: test, Partition: 1
   ```

**常見故障和解決方案**  
以下說明常見的 MSK Replicator 失敗，以及如何緩解這些故障。

**訊息大小大於 max.request.size**  
*原因：*個別訊息大小超過 10 MB （預設上限）。  
以下是此失敗訊息類型的範例。  

```
ReplicatorException: The message is 20635370 bytes when serialized which is larger than 10485760, which is the value of the max.request.size configuration. Topic: test, Partition: 1
```
*解決方案：*減少主題中的個別訊息大小。如果不能，請遵循[請求提高限制](limits.md#request-msk-quota-increase)的指示。

**訊息大小大於伺服器將接受的最大訊息大小**  
*原因：*訊息大小超過目標叢集的訊息大小上限。  
以下是此失敗訊息類型的範例。  

```
ReplicatorException: The request included a message larger than the max message size the server will accept. Topic: test, Partition: 1
```
*解決方案：*增加目標叢集或主題的`max.message.bytes`組態。請參閱 [max.message.bytes](https://kafka.apache.org/documentation/#topicconfigs_max.message.bytes)。

**時間戳記超出範圍**  
*原因：*訊息時間戳記超出目標叢集的允許範圍。  
以下是此失敗訊息類型的範例。  

```
ReplicatorException: Timestamp 1730137653724 of message with offset 0 is out of range. The timestamp should be within [1730137892239, 1731347492239] Topic: test, Partition: 1
```
*解決方案：*更新目標叢集的`message.timestamp.before.max.ms`組態。請參閱 https：//[message.timestamp.before.max.ms](https://kafka.apache.org/documentation/#topicconfigs_message.timestamp.before.max.ms)。

**記錄批次過大**  
*原因：*記錄批次大小超過為目標叢集上的主題設定的區段大小。MSK Replicator 支援最大批次大小為 1 MB。  
以下是此失敗訊息類型的範例。  

```
ReplicatorException: The request included message batch larger than the configured segment size on the server. Topic: test, Partition: 1
```
*解決方案：*將目標叢集的 更新`segment.bytes`為至少 1048576 (1 MB)。請參閱 [segment.bytes](https://kafka.apache.org/documentation/#topicconfigs_segment.bytes)。

**注意**  
如果`ReplicatorFailure`指標在套用這些解決方案後繼續發出非零值，請重複疑難排解程序，直到指標發出零值。

## 針對自我管理 Kafka 叢集的複寫進行故障診斷
<a name="msk-replicator-ts-external"></a>

### MSK Replicator 無法連線至自我管理的 Kafka 叢集
<a name="msk-replicator-ts-external-connect"></a>

如果 MSK Replicator 無法連線至自我管理的 Kafka 叢集，請執行下列檢查：

1. 確認您的 VPN 或 Direct Connect 連線處於作用中狀態，且路由表正確。

1. 確認安全群組允許來自 SASL\_SSL 連接埠上 MSK Replicator 子網路的傳入流量 （通常是 9096)。

1. 驗證從 VPC 到自我管理叢集代理程式主機名稱的 DNS 解析。

1. 檢查 `KafkaClusterPingSuccessCount` Amazon CloudWatch 中的指標 — 值 0 表示連線失敗。

### SASL/SCRAM 身分驗證失敗
<a name="msk-replicator-ts-external-sasl"></a>

如果`AuthError`指標不是零或複寫器日誌顯示 SASL/SCRAM 錯誤：

1. 確認存放在 AWS Secrets Manager 中的登入資料符合自我管理叢集上的 SCRAM 使用者登入資料。

1. 確認 SCRAM 使用者具有必要的 ACL 許可 （閱讀、主題說明、閱讀、取用者群組說明、叢集說明）。

1. 檢查 `AuthError` 指標以確認身分驗證錯誤，並使用 `ClusterAlias`維度識別來源或目標叢集是否受到影響。

### SSL 憑證問題
<a name="msk-replicator-ts-external-ssl"></a>

如果複寫器無法建立與自我管理叢集的安全連線：

1. 確認 AWS Secrets Manager 中的`certificate`值包含 PEM 格式的完整 CA 憑證鏈。

1. 確認已在所有自我管理叢集代理程式上設定 SSL 接聽程式。

1. 確認憑證尚未過期，並由信任的 CA 發出。

### 自我管理叢集的取用者群組偏移同步失敗
<a name="msk-replicator-ts-external-offsets"></a>

如果取用者群組位移未正確同步：

1. 驗證`ConsumerGroupOffsetSyncFailure`指標 — 應為 0。

1. 確認取用者群組正在來源叢集上積極消費 （非作用中取用者群組可能不會同步）。

1. 對於雙向複寫，請確認兩個複寫器`true`上的 `synchroniseConsumerGroupOffsets` 都設為 。