Questa pagina è stata tradotta dall'API Cloud Translation.

Risoluzione dei problemi di migrazione

Questa sezione fornisce suggerimenti per la risoluzione dei problemi comuni che possono verificarsi durante la creazione e la gestione delle pipeline Datastream e Dataflow.

Risoluzione dei problemi relativi a un profilo di connessione Datastream

La procedura di migrazione richiede la creazione di due profili di connessione Datastream: uno per la lettura dei dati dal database compatibile con MongoDB di origine e un altro per la scrittura dei dati in un bucket Cloud Storage.

Questi passaggi utilizzano il comando gcloud datastream connection-profiles create. Quando crei un profilo di connessione Datastream con questo comando, vengono restituiti metadati simili a quelli dell'esempio seguente:

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

Puoi utilizzare l'identificatore evidenziato che inizia con operation- per recuperare lo stato dell'operazione Datastream specificata. Per l'esempio di output precedente, il seguente comando gcloud CLI recupera i dettagli della richiesta di creazione del profilo di connessione:

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

Puoi esaminare i profili di connessione Datastream e altri artefatti Datastream nella console Google Cloud .

Nella console Google Cloud , vai alla pagina Datastream:

Vai a Datastream

Risoluzione dei problemi relativi a uno stream Datastream

Quando crei uno stream Datastream con il comando gcloud datastream streams create, vengono restituiti metadati simili al seguente esempio:

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

Puoi utilizzare l'identificatore evidenziato che inizia con operation- per recuperare lo stato dell'operazione Datastream specificata. Per l'esempio di output riportato sopra, il seguente comando gcloud CLI recupera i dettagli della richiesta di creazione dello stream:

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

Per cercare lo stato di un flusso esistente, utilizza:

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

Puoi esaminare gli stream Datastream e altri artefatti Datastream nella console Google Cloud .

Nella console Google Cloud , vai alla pagina Datastream:

Vai a Datastream

Risoluzione dei problemi della pipeline Dataflow

Puoi monitorare l'esecuzione della pipeline Dataflow nella console Google Cloud .

Nella console Google Cloud , vai alla pagina Dataflow:

Vai a Dataflow

Risoluzione dei problemi relativi agli errori riproducibili

Gli errori non irreversibili sono errori temporanei che alla fine andranno a buon fine. Gli errori comuni che possono essere riprovati sono:

Problemi di rete o connettività
Contesa delle transazioni
Connessioni chiuse a causa del bilanciamento del carico

I documenti che non è stato possibile scrivere nella destinazione a causa di errori verranno memorizzati nel bucket Cloud Storage, nella posizione specificata dal parametro deadLetterQueueDirectory del modello Dataflow. Per impostazione predefinita, i tentativi di ripetizione degli errori non irreversibili verranno eseguiti fino al numero di volte specificato dal parametro dlqMaxRetryCount.

La coda dei messaggi non recapitabili (DLQ) può essere ispezionata direttamente da Cloud Storage accedendo al percorso specificato nella DLQ_LOCATION variabile di ambiente. Il percorso conterrà una gerarchia di cartelle con timestamp, contenenti record JSON di documenti e aggiornamenti che non è stato possibile scrivere nel database Firestore con compatibilità MongoDB.

Supponendo che la coda dei messaggi non recapitabili contenga solo documenti non riusciti a causa di errori ripetibili, puoi tentare di svuotare la coda eseguendo il modello Dataflow in una modalità che opera solo su questa coda. Per farlo, imposta il parametro runMode su retryDLQ, come mostrato nell'esempio seguente:

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

Risoluzione degli errori non riproducibili

Gli errori comuni non riproducibili sono:

Tipi BSON non supportati
Tipi BSON non supportati utilizzati come _id
0L non supportato come _id
Dimensioni dei documenti superiori al limite di 4 MB di Firestore

Gli errori non riproducibili verranno archiviati nel bucket Cloud Storage, nella posizione specificata dal parametro deadLetterQueueDirectory del modello Dataflow.

Esaminare la coda di messaggi non recapitabili (DLQ)

Una volta interrotta tutta l'elaborazione, il che significa che non viene elaborato traffico attivo e non vengono ritentati eventi con errori, gli eventi con errori vengono salvati in modo permanente in Cloud Storage.

Puoi verificare che l'elaborazione sia stata interrotta controllando gli eventi di scrittura transazionale e verificando che non ci sia throughput di elaborazione e che non vengano generate nuove voci di log.

Puoi ispezionare la DLQ direttamente da Cloud Storage:

Vai alla località Cloud Storage specificata nella variabile di ambiente DLQ_LOCATION.
Nell'albero delle cartelle nidificate create in base ai timestamp, espandi le cartelle per visualizzare i contenuti più recenti nella coda. I file potrebbero essere stati suddivisi in shard e avere il seguente aspetto:
Esamina ogni file per visualizzare i documenti e gli aggiornamenti che non sono stati applicati al database di destinazione. Ogni messaggio conterrà un payload dell'evento originale e dell'eccezione che si è verificata.

Esiste una possibilità molto bassa che si verifichino errori ripetibili, soprattutto se è stato utilizzato un valore basso per il parametro dlqMaxRetryCount, ma in genere gli eventi che finiscono nella DLQ non sono ripetibili per i motivi descritti in precedenza.
Scegli di interrompere la migrazione e riprendere il traffico dell'applicazione verso il database di origine, risolvendo i vincoli dei dati di Firestore nel database di origine e rieseguendo l'intero processo di migrazione oppure puoi risolvere i problemi relativi ai dati con ogni evento DLQ e riprovare a elaborare questi eventi.

Per ogni riga di ogni file DLQ puoi:

Converti i tipi di dati non supportati in un tipo di dati alternativo modificando il payload del documento. Il payload del documento sarà nel formato JSON canonico esteso. Esprimi il nuovo tipo di dati nel formato JSON esteso canonico.
Riassegna il documento 0L _id a un nuovo valore Long o a un tipo di dati diverso, ad esempio String. La riassegnazione a un tipo di dati diverso potrebbe richiedere modifiche alla logica dell'applicazione se le aspettative del codice esistente sono che tutti i _id siano di tipo Long.
I documenti che superano il limite di 4 MB di Firestore possono essere suddivisi in documenti più piccoli o i loro contenuti possono essere compressi. Tuttavia, ciò richiederebbe modifiche alla logica dell'applicazione per gestire i dati.
Ignora l'evento eliminando la riga dal file DLQ.

Per modificare i file DLQ, devi scaricare i file .json in locale, modificarne i contenuti e ricaricarli nella stessa posizione di Cloud Storage, sovrascrivendo il file originale. Se tutti i documenti a cui viene fatto riferimento nel file possono essere esclusi in sicurezza dalla migrazione, allora l'intero file può essere eliminato.

Dopo aver apportato le modifiche ai file DLQ, puoi eseguire di nuovo questi eventi tramite il modello Dataflow di migrazione in modalità retryDLQ.

Il comando seguente avvia una nuova pipeline Dataflow che elaborerà solo gli elementi nella coda di messaggi non recapitabili:

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

Passaggi successivi

Torna a Eseguire la migrazione a Firestore con compatibilità MongoDB.