Pemecahan masalah migrasi

Bagian ini memberikan tips tentang cara memecahkan masalah umum yang dapat muncul saat membuat dan mengelola pipeline Datastream dan Dataflow.

Memecahkan masalah profil koneksi Datastream

Prosedur migrasi mengharuskan Anda membuat dua profil koneksi Datastream: satu untuk membaca data dari database yang kompatibel dengan MongoDB sumber dan satu lagi untuk menulis data ke dalam bucket Cloud Storage.

Langkah-langkah ini menggunakan perintah gcloud datastream connection-profiles create. Saat Anda membuat profil koneksi Datastream dengan perintah ini, profil tersebut akan menampilkan metadata yang mirip dengan contoh berikut:

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

Anda dapat menggunakan ID yang ditandai dan diawali dengan operation- untuk mengambil status operasi Datastream tertentu. Untuk contoh output di atas, perintah gcloud CLI berikut mengambil detail tentang permintaan pembuatan profil koneksi:

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

Anda dapat memeriksa profil koneksi Datastream dan artefak Datastream lainnya di konsol Google Cloud .

Di konsol Google Cloud , buka halaman Datastream:

Buka Datastream

Memecahkan masalah aliran Datastream

Saat Anda membuat aliran Datastream dengan perintah gcloud datastream streams create, perintah tersebut akan menampilkan metadata yang mirip dengan contoh berikut:

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

Anda dapat menggunakan ID yang ditandai dan diawali dengan operation- untuk mengambil status operasi Datastream tertentu. Untuk contoh output di atas, perintah gcloud CLI berikut mengambil detail tentang permintaan pembuatan streaming:

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

Untuk mencari status streaming yang ada, gunakan:

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

Anda dapat memeriksa aliran Datastream dan artefak Datastream lainnya di konsol Google Cloud .

Di konsol Google Cloud , buka halaman Datastream:

Buka Datastream

Memecahkan masalah pipeline Dataflow

Anda dapat memantau eksekusi pipeline Dataflow di Google Cloud console.

Di konsol Google Cloud , buka halaman Dataflow:

Buka Dataflow

Memecahkan masalah error yang dapat dicoba lagi

Error yang dapat dicoba lagi adalah error sementara yang pada akhirnya akan berhasil. Error umum yang dapat dicoba lagi adalah:

  • Masalah jaringan atau konektivitas
  • Persaingan transaksi
  • Koneksi ditutup karena load balancing

Dokumen yang tidak dapat ditulis ke tujuan karena error akan disimpan di bucket Cloud Storage, di lokasi yang ditentukan oleh parameter deadLetterQueueDirectory template Dataflow. Error yang dapat dicoba lagi secara default akan dicoba lagi hingga jumlah kali yang ditentukan oleh parameter dlqMaxRetryCount.

Antrean Surat yang Tidak Terkirim (DLQ) dapat diperiksa langsung dari Cloud Storage dengan membuka jalur yang ditentukan dalam DLQ_LOCATION variabel lingkungan. Jalur akan berisi hierarki folder yang diberi stempel waktu, yang berisi catatan json dokumen dan update yang tidak dapat ditulis ke database Firestore dengan kompatibilitas MongoDB.

Dengan asumsi bahwa Antrean Surat Mati hanya berisi dokumen yang gagal karena error yang dapat dicoba ulang, Anda dapat mencoba menguras antrean dengan menjalankan template Dataflow dalam mode yang hanya beroperasi pada antrean ini. Untuk melakukannya, tetapkan parameter runMode ke retryDLQ, seperti yang ditunjukkan dalam contoh berikut:

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

Memecahkan masalah error yang tidak dapat dicoba lagi

Error umum yang tidak dapat dicoba lagi adalah:

  • Jenis BSON yang tidak didukung
  • Jenis BSON yang tidak didukung digunakan sebagai _id
  • 0L tidak didukung sebagai _id
  • Ukuran dokumen lebih besar dari batas 4 MB Firestore

Error yang tidak dapat dicoba lagi akan disimpan di bucket Cloud Storage, di lokasi yang ditentukan oleh parameter deadLetterQueueDirectory template Dataflow.

Memeriksa Dead Letter Queue (DLQ)

Setelah semua pemrosesan berhenti, yang berarti tidak ada traffic aktif yang sedang diproses dan tidak ada peristiwa yang error yang sedang dicoba ulang, peristiwa yang error akan dipertahankan ke Cloud Storage.

Anda dapat memverifikasi bahwa pemrosesan telah berhenti dengan memeriksa peristiwa Penulisan transaksional dan mengonfirmasi bahwa tidak ada throughput pemrosesan dan tidak ada entri log baru yang dibuat.

Anda dapat memeriksa DLQ langsung dari Cloud Storage:

  1. Buka lokasi Cloud Storage yang ditentukan dalam variabel lingkungan DLQ_LOCATION.

  2. Di struktur folder bertingkat yang dibuat sesuai dengan stempel waktu, luaskan folder untuk melihat konten terbaru dalam antrean. File dapat di-shard dan terlihat seperti contoh berikut:

    File di DLQ

  3. Periksa setiap file untuk melihat dokumen dan update yang tidak diterapkan ke database tujuan. Setiap pesan akan berisi payload dari peristiwa asli dan pengecualian yang terjadi.

    Kemungkinan besar tidak ada kesalahan yang dapat dicoba ulang, terutama jika nilai rendah untuk parameter dlqMaxRetryCount digunakan, tetapi umumnya peristiwa yang berakhir di DLQ tidak dapat dicoba ulang karena alasan yang dijelaskan sebelumnya.

  4. Pilih untuk membatalkan migrasi dan melanjutkan traffic aplikasi ke database sumber, mengatasi batasan data Firestore di database sumber dan menjalankan ulang seluruh proses migrasi, atau Anda dapat mengatasi masalah data dengan setiap peristiwa DLQ dan mencoba lagi pemrosesan peristiwa ini.

Untuk setiap baris di setiap file DLQ, Anda dapat:

  • Konversi jenis data yang tidak didukung ke jenis data alternatif dengan mengedit payload dokumen. Payload dokumen akan menggunakan format JSON yang diperluas kanonis. Nyatakan jenis data baru dalam format JSON yang diperluas kanonis.

  • Tetapkan ulang dokumen 0L _id ke Long baru atau ke jenis data lain seperti String. Penetapan ulang ke jenis data yang berbeda mungkin memerlukan perubahan logika aplikasi jika ekspektasi kode yang ada adalah bahwa semua _id adalah Long.

  • Dokumen yang melebihi batas 4 MB Firestore dapat dipisahkan menjadi dokumen yang lebih kecil atau isinya dapat dikompresi. Namun, hal ini akan memerlukan perubahan pada logika aplikasi untuk menangani data.

  • Abaikan peristiwa dengan menghapus baris dari file DLQ.

Untuk mengubah file DLQ, Anda harus mendownload file .json secara lokal, mengubah isinya, dan menguploadnya kembali ke lokasi Cloud Storage yang sama, sehingga menggantikan file asli. Jika semua dokumen yang dirujuk dalam file dapat dikecualikan dengan aman dari migrasi, maka seluruh file dapat dihapus.

Setelah melakukan modifikasi pada file DLQ, Anda dapat menjalankan ulang peristiwa ini melalui template Dataflow migrasi dalam mode retryDLQ.

Perintah berikut memulai pipeline Dataflow baru yang hanya akan memproses item dalam Dead Letter Queue:

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

Langkah berikutnya