Pemecahan masalah migrasi

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 sumber yang kompatibel dengan MongoDB 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, metadata akan ditampilkan 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 yang dimulai dengan operation- untuk mengambil status operasi Datastream yang diberikan. 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 Google Cloud konsol, buka halaman Datastream:

Buka Datastream

Memecahkan masalah aliran data Datastream

Saat Anda membuat aliran data Datastream dengan perintah gcloud datastream streams create, metadata akan ditampilkan 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 yang dimulai dengan operation- untuk mengambil status operasi Datastream yang diberikan. Untuk contoh output di atas, perintah gcloud CLI berikut mengambil detail tentang permintaan pembuatan aliran data:

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

Untuk mencari status aliran data yang ada, gunakan:

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

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

Di Google Cloud konsol, buka halaman Datastream:

Buka Datastream

Memecahkan masalah pipeline Dataflow

Anda dapat memantau eksekusi pipeline Dataflow di Google Cloud konsol.

Di Google Cloud konsol, 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 dari template Dataflow. Secara default, error yang dapat dicoba lagi akan dicoba lagi hingga jumlah yang ditentukan oleh parameter dlqMaxRetryCount.

Dead Letter Queue (DLQ) dapat diperiksa langsung dari Cloud Storage dengan membuka jalur yang ditentukan dalam DLQ_LOCATION variabel lingkungan. Jalur tersebut akan berisi hierarki folder yang diberi stempel waktu, yang berisi rekaman json dokumen dan pembaruan yang tidak dapat ditulis ke database Firestore dengan kompatibilitas MongoDB.

Dengan asumsi bahwa Dead Letter Queue hanya berisi dokumen yang gagal karena error yang dapat dicoba lagi, 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 yang digunakan sebagai _id
• 0L yang tidak didukung sebagai _id
• Ukuran dokumen lebih besar dari batas 16 MB Firestore

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

Memeriksa Dead Letter Queue (DLQ)

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

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

Anda dapat memeriksa DLQ langsung dari Cloud Storage:

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

2. Di hierarki folder bertingkat yang dibuat menurut stempel waktu, luaskan folder untuk melihat konten terbaru dalam antrean. File mungkin telah di-shard dan terlihat seperti contoh berikut:

   

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

   Kemungkinan error yang dapat dicoba lagi sangat kecil, terutama jika nilai rendah untuk parameter dlqMaxRetryCount digunakan, tetapi umumnya peristiwa yang berakhir di DLQ tidak akan dapat dicoba lagi 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:

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

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

• Dokumen yang melebihi batas 16 MB Firestore dapat dipisahkan menjadi dokumen yang lebih kecil atau kontennya 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 konten, dan menguploadnya kembali ke lokasi Cloud Storage yang sama, dengan menimpa file asli. Jika semua dokumen yang direferensikan dalam file dapat dikecualikan dengan aman dari migrasi, seluruh file dapat dihapus.

Setelah melakukan perubahan 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

• Kembali ke Bermigrasi ke Firestore dengan kompatibilitas MongoDB.