Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

移行のトラブルシューティング

このセクションでは、Datastream パイプラインと Dataflow パイプラインの作成と管理で発生する一般的な問題のトラブルシューティングについて説明します。

Datastream 接続プロファイルのトラブルシューティング

移行手順では、2 つの Datastream 接続プロファイルを作成する必要があります。1 つは移行元 MongoDB 互換データベースからデータを読み取るためのプロファイル、もう 1 つはデータを Cloud Storage バケットに書き込むためのプロファイルです。

これらの手順では、gcloud datastream connection-profiles create コマンドを使用します。このコマンドで Datastream 接続プロファイルを作成すると、次の例のようなメタデータが返されます。

metadata:
  '@type': type.googleapis.com/google.cloud.datastream.v1.OperationMetadata
  apiVersion: v1
  createTime: '2025-05-15T21:49:05.022509533Z'
  requestedCancellation: false
  target: projects/PROJECT_ID/locations/LOCATION/connectionProfiles/SRC_CONNECTION_PROFILE_NAME
  verb: create
name: projects/PROJECT_ID/locations/LOCATION/operations/operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6

ハイライト表示された operation- で始まる識別子を使用して、指定された Datastream オペレーションのステータスを取得できます。上記の出力例では、次の gcloud CLI コマンドで接続プロファイル作成リクエストの詳細を取得します。

gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"

Datastream 接続プロファイルやその他の Datastream アーティファクトは、 Google Cloud コンソールで確認できます。

コンソールで、[Datastream] ページに移動します。 Google Cloud

Datastream に移動

Datastream ストリームのトラブルシューティング

gcloud datastream streams create コマンドで Datastream ストリームを作成すると、次の例のようなメタデータが返されます。

metadata:
  '@type': type.googleapis.com/google.cloud.datastream.v1.OperationMetadata
  apiVersion: v1
  createTime: '2025-05-14T19:31:20.209503095Z'
  requestedCancellation: false
  target: projects/PROJECT_ID/locations/LOCATION/streams/DATASTREAM_NAME
  verb: create
  name: projects/PROJECT_ID/locations/LOCATION/operations/operation-1747251080085-6351d97f63eb8-43204f78-35c87474

ハイライト表示された operation- で始まる識別子を使用して、指定された Datastream オペレーションのステータスを取得できます。上記の出力例では、次の gcloud CLI コマンドでストリーム作成リクエストの詳細を取得します。

gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"

既存のストリームのステータスを調べるには、次のようにします。

gcloud datastream streams describe $DATASTREAM_NAME --location=$LOCATION

Datastream ストリームやその他の Datastream アーティファクトは、 Google Cloud コンソールで確認できます。

コンソールで、[Datastream] ページに移動します。 Google Cloud

Datastream に移動

Dataflow パイプラインのトラブルシューティング

Dataflow パイプラインの実行は、 Google Cloud コンソールでモニタリングできます。

コンソールで、[Dataflow] ページに移動します。 Google Cloud

Dataflow に移動

再試行可能なエラーのトラブルシューティング

再試行可能なエラーは、最終的に成功する一時的なエラーです。一般的な再試行可能なエラーは次のとおりです。

ネットワークまたは接続の問題
トランザクションの競合
負荷分散による接続の切断

エラーのために宛先に書き込めなかったドキュメントは、Cloud Storage バケットの Dataflow テンプレートの deadLetterQueueDirectory パラメータで指定された場所に保存されます。再試行可能なエラーは、デフォルトで dlqMaxRetryCount パラメータで指定された回数まで再試行されます。

デッドレターキュー（DLQ）は、 Cloud Storage から、 DLQ_LOCATION 環境変数で指定されたパスに移動することで直接検査できます。このパスには、タイムスタンプ付きフォルダの階層が含まれます。このフォルダには、MongoDB 互換の Firestore データベースに書き込めなかったドキュメントと更新の JSON レコードが含まれています。

デッドレターキューに再試行可能なエラーが原因で失敗したドキュメントのみが含まれていると仮定すると、このキューでのみ動作するモードで Dataflow テンプレートを実行して、キューをドレインできます。これを行うには、次の例に示すように、runMode パラメータを retryDLQ に設定します。

DLQ_START_TIME="$(date +'%Y%m%d%H%M%S')"

gcloud dataflow flex-template run "dataflow-mongodb-to-firestore-$DLQ_START_TIME" \
--template-file-gcs-location gs://dataflow-templates-us-central1/latest/flex/Cloud_Datastream_MongoDB_to_Firestore \
--region $LOCATION \
--num-workers $NUM_WORKERS \
--temp-location $TEMP_OUTPUT_LOCATION \
--additional-user-labels "" \
--parameters inputFilePattern=$INPUT_FILE_LOCATION,\
inputFileFormat=avro,\
fileReadConcurrency=10,\
connectionUri=$FIRESTORE_CONNECTION_URI,\
databaseName=$FIRESTORE_DATABASE_NAME,\
shadowCollectionPrefix=shadow_,\
batchSize=500,\
deadLetterQueueDirectory=$DLQ_LOCATION,\
dlqRetryMinutes=10,\
dlqMaxRetryCount=500,\
processBackfillFirst=false,\
runMode=retryDLQ,\
directoryWatchDurationInMinutes=10,\
streamName=$DATASTREAM_NAME,\
stagingLocation=$STAGING_LOCATION,\
autoscalingAlgorithm=THROUGHPUT_BASED,\
maxNumWorkers=$MAX_WORKERS,\
workerMachineType=$WORKER_TYPE

再試行できないエラーのトラブルシューティング

一般的な再試行できないエラーは次のとおりです。

サポートされていない BSON 型
_id として使用されるサポートされていない BSON 型
_id としてサポートされていない 0L
Firestore の 16 MB の上限を超えるドキュメントサイズ

再試行できないエラーは、Cloud Storage バケットの Dataflow テンプレートの deadLetterQueueDirectory パラメータで指定された場所に保存されます。

デッドレターキュー（DLQ）の検査

すべての処理が停止した後（アクティブなトラフィックが処理されず、エラーが発生したイベントが再試行されない場合）、エラーが発生したイベントは Cloud Storage に保存されます。

処理が停止したことを確認するには、トランザクション書き込みイベントを検査し、処理スループットがないこと、新しいログエントリが生成されていないことを確認します。

DLQ は Cloud Storage から直接検査できます。

DLQ_LOCATION 環境変数で指定された Cloud Storage の場所に移動します。
タイムスタンプに従って構築されたネストされたフォルダのツリーで、フォルダを開いてキュー内の最新のコンテンツを表示します。ファイルはシャーディングされている可能性があり、次の例のようになります。
各ファイルを検査して、宛先データベースに適用されなかったドキュメントと更新を表示します。各メッセージには、元のイベントのペイロードと発生した例外が含まれます。

特に dlqMaxRetryCount パラメータに小さい値が使用されている場合は、再試行可能なエラーが存在する可能性は非常に低いですが、通常、DLQ に到達するイベントは、前述の理由により再試行できません。
移行を中止して、ソースデータベースへのアプリケーショントラフィックを再開し、ソースデータベースの Firestore データ制約に対処して、移行プロセス全体を再実行するか、各 DLQ イベントでデータの問題に対処して、これらのイベントの処理を再試行します。

各 DLQ ファイルの各行に対して、次の操作を行うことができます。

ドキュメントペイロードを編集して、サポートされていないデータ型を代替データ型に変換します。ドキュメントペイロードは、正規の拡張 JSON 形式になります。新しいデータ型を正規の拡張 JSON 形式で表します。
0L ドキュメント _id を新しい Long または String などの別のデータ型に再割り当てします。別のデータ型に再割り当てする場合、既存のコードで _id がすべて Long であることが想定されている場合は、アプリケーションロジックの変更が必要になることがあります。
Firestore の 16 MB の上限を超えるドキュメントは、小さなドキュメントに分割するか、コンテンツを圧縮できます。ただし、これにはデータを処理するためのアプリケーションロジックの変更が必要になります。
DLQ ファイルから行を削除して、イベントを無視します。

DLQ ファイルを変更するには、.json ファイルをローカルにダウンロードし、内容を変更して、元のファイルを上書きして同じ Cloud Storage の場所に再アップロードする必要があります。ファイルで参照されているすべてのドキュメントを移行から安全に除外できる場合は、ファイル全体を削除できます。

DLQ ファイルを変更したら、retryDLQ モードで移行 Dataflow テンプレートを使用して、これらのイベントを再実行できます。

次のコマンドは、デッドレターキュー内のアイテムのみを処理する新しい Dataflow パイプラインを開始します。

DLQ_START_TIME="$(date +'%Y%m%d%H%M%S')"

gcloud dataflow flex-template run "dataflow-mongodb-to-firestore-$DLQ_START_TIME" \
--template-file-gcs-location gs://dataflow-templates-us-central1/latest/flex/Cloud_Datastream_MongoDB_to_Firestore \
--region $LOCATION \
--num-workers $NUM_WORKERS \
--temp-location $TEMP_OUTPUT_LOCATION \
--additional-user-labels "" \
--parameters inputFilePattern=$INPUT_FILE_LOCATION,\
inputFileFormat=avro,\
fileReadConcurrency=10,\
connectionUri=$FIRESTORE_CONNECTION_URI,\
databaseName=$FIRESTORE_DATABASE_NAME,\
shadowCollectionPrefix=shadow_,\
batchSize=500,\
deadLetterQueueDirectory=$DLQ_LOCATION,\
dlqRetryMinutes=10,\
dlqMaxRetryCount=500,\
processBackfillFirst=false,\
runMode=retryDLQ,\
directoryWatchDurationInMinutes=10,\
streamName=$DATASTREAM_NAME,\
stagingLocation=$STAGING_LOCATION,\
autoscalingAlgorithm=THROUGHPUT_BASED,\
maxNumWorkers=$MAX_WORKERS,\
workerMachineType=$WORKER_TYPE

次のステップ

MongoDB 互換の Firestore への移行に戻る。