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:
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:
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:
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