Diese Seite wurde von der Cloud Translation API übersetzt.

Fehlerbehebung bei der Migration

In diesem Abschnitt finden Sie Tipps zur Behebung häufiger Probleme, die beim Erstellen und Verwalten von Datastream- und Dataflow-Pipelines auftreten können.

Fehlerbehebung bei einem Datastream-Verbindungsprofil

Für die Migration müssen Sie zwei Datastream-Verbindungsprofile erstellen: eines zum Lesen von Daten aus der MongoDB-kompatiblen Quelldatenbank und eines zum Schreiben der Daten in einen Cloud Storage-Bucket.

Bei diesen Schritten wird der Befehl gcloud datastream connection-profiles create verwendet. Wenn Sie mit diesem Befehl ein Datastream-Verbindungsprofil erstellen, werden Metadaten zurückgegeben, die dem folgenden Beispiel ähneln:

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

Mit der hervorgehobenen Kennung, die mit operation- beginnt, können Sie den Status des angegebenen Datastream-Vorgangs abrufen. Im obigen Beispiel für die Ausgabe wird mit dem folgenden gcloud CLI-Befehl nach Details zur Anfrage zum Erstellen des Verbindungsprofils gesucht:

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

Sie können Datastream-Verbindungsprofile und andere Datastream-Artefakte in der Google Cloud Console untersuchen.

Rufen Sie in der Google Cloud Console die Seite Datastream auf:

Zu Datastream

Fehlerbehebung bei einem Datastream-Stream

Wenn Sie einen Datastream-Stream mit dem Befehl gcloud datastream streams create erstellen, werden Metadaten zurückgegeben, die dem folgenden Beispiel ähneln:

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

Mit der hervorgehobenen Kennung, die mit operation- beginnt, können Sie den Status des angegebenen Datastream-Vorgangs abrufen. Im obigen Beispiel für die Ausgabe ruft der folgende gcloud CLI-Befehl Details zur Anfrage zum Erstellen des Streams ab:

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

So rufen Sie den Status eines vorhandenen Streams auf:

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

Sie können Datastream-Streams und andere Datastream-Artefakte in der Google Cloud -Konsole untersuchen.

Rufen Sie in der Google Cloud Console die Seite Datastream auf:

Zu Datastream

Fehlerbehebung bei der Dataflow-Pipeline

Sie können die Ausführung der Dataflow-Pipeline in der Google Cloud Console überwachen.

Rufen Sie in der Google Cloud Console die Seite Dataflow auf:

Zu Dataflow

Behebbare Fehler beheben

Wiederholbare Fehler sind vorübergehende Fehler, die letztendlich behoben werden. Häufige wiederholbare Fehler:

Netzwerk- oder Verbindungsprobleme
Transaktionskonflikte
Geschlossene Verbindungen aufgrund von Load Balancing

Dokumente, die aufgrund von Fehlern nicht in das Ziel geschrieben werden konnten, werden im Cloud Storage-Bucket an dem Speicherort gespeichert, der durch den Parameter deadLetterQueueDirectory der Dataflow-Vorlage angegeben wird. Wiederholbare Fehler werden standardmäßig bis zur Anzahl der Wiederholungen wiederholt, die durch den Parameter dlqMaxRetryCount angegeben wird.

Die Dead-Letter-Warteschlange (DLQ) kann direkt über Cloud Storage aufgerufen werden. Rufen Sie dazu den Pfad auf, der in der DLQ_LOCATION-Umgebungsvariable angegeben ist. Der Pfad enthält eine Hierarchie von Ordnern mit Zeitstempel, die JSON-Datensätze von Dokumenten und Aktualisierungen enthalten, die nicht in die Firestore-Datenbank mit MongoDB-Kompatibilität geschrieben werden konnten.

Angenommen, die Dead-Letter-Warteschlange enthält nur Dokumente, die aufgrund von wiederholbaren Fehlern fehlgeschlagen sind. In diesem Fall können Sie versuchen, die Warteschlange zu leeren, indem Sie die Dataflow-Vorlage in einem Modus ausführen, der nur für diese Warteschlange gilt. Legen Sie dazu den Parameter runMode auf retryDLQ fest, wie im folgenden Beispiel gezeigt:

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

Nicht wiederholbare Fehler beheben

Häufige nicht wiederholbare Fehler:

Nicht unterstützte BSON-Typen
Nicht unterstützte BSON-Typen, die als _id verwendet werden
0L als _id nicht unterstützt
Dokumente, die größer als das Firestore-Limit von 4 MB sind

Nicht wiederholbare Fehler werden im Cloud Storage-Bucket am Speicherort gespeichert, der durch den Parameter deadLetterQueueDirectory der Dataflow-Vorlage angegeben wird.

Dead-Letter-Warteschlange (DLQ) untersuchen

Nachdem die gesamte Verarbeitung beendet wurde, d. h. kein aktiver Traffic verarbeitet wird und keine fehlerhaften Ereignisse wiederholt werden, werden die fehlerhaften Ereignisse in Cloud Storage gespeichert.

Sie können prüfen, ob die Verarbeitung beendet wurde, indem Sie transaktionale Schreibvorgänge untersuchen und bestätigen, dass kein Verarbeitungsdurchsatz vorhanden ist und keine neuen Logeinträge generiert werden.

Sie können die DLQ direkt in Cloud Storage prüfen:

Rufen Sie den Cloud Storage-Speicherort auf, der in der Umgebungsvariable DLQ_LOCATION angegeben ist.
Maximieren Sie im Baum der verschachtelten Ordner, der anhand der Zeitstempel erstellt wurde, die Ordner, um die neuesten Inhalte in der Warteschlange zu sehen. Die Dateien könnten in Shards aufgeteilt worden sein und wie im folgenden Beispiel aussehen:
Sehen Sie sich jede Datei an, um die Dokumente und Updates zu sehen, die nicht auf die Zieldatenbank angewendet wurden. Jede Nachricht enthält eine Nutzlast mit dem ursprünglichen Ereignis und der aufgetretenen Ausnahme.

Es ist sehr unwahrscheinlich, dass wiederholbare Fehler auftreten, insbesondere wenn ein niedriger Wert für den Parameter dlqMaxRetryCount verwendet wurde. Im Allgemeinen sind Ereignisse, die in der DLQ landen, aus den oben beschriebenen Gründen jedoch nicht wiederholbar.
Sie können die Migration entweder abbrechen und den Anwendungs-Traffic zur Quelldatenbank zurückleiten, die Firestore-Datenbeschränkungen in der Quelldatenbank beheben und den gesamten Migrationsprozess noch einmal ausführen. Alternativ können Sie die Datenprobleme mit jedem DLQ-Ereignis beheben und die Verarbeitung dieser Ereignisse noch einmal versuchen.

Für jede Zeile in jeder DLQ-Datei haben Sie folgende Möglichkeiten:

Konvertieren Sie die nicht unterstützten Datentypen in einen alternativen Datentyp, indem Sie die Dokumentnutzlast bearbeiten. Die Dokumentnutzlast hat das kanonische erweiterte JSON-Format. Geben Sie den neuen Datentyp im kanonischen erweiterten JSON-Format an.
Weisen Sie das 0L-Dokument _id einem neuen Long oder einem anderen Datentyp wie String zu. Die Neuzuweisung zu einem anderen Datentyp erfordert möglicherweise Änderungen an der Anwendungslogik, wenn der vorhandene Code davon ausgeht, dass alle _id-Werte vom Typ „Long“ sind.
Dokumente, die das Firestore-Limit von 4 MB überschreiten, können in kleinere Dokumente aufgeteilt oder ihr Inhalt kann komprimiert werden. Dazu wären jedoch Änderungen an der Anwendungslogik erforderlich, um die Daten zu verarbeiten.
Ignorieren Sie das Ereignis, indem Sie die Zeile aus der DLQ-Datei löschen.

Wenn Sie die DLQ-Dateien ändern möchten, müssen Sie die JSON-Datei(en) lokal herunterladen, den Inhalt ändern und sie dann wieder an denselben Cloud Storage-Speicherort hochladen, wodurch die Originaldatei überschrieben wird. Wenn alle in der Datei referenzierten Dokumente sicher von der Migration ausgeschlossen werden können, kann die gesamte Datei gelöscht werden.

Nachdem Sie die Änderungen an den DLQ-Dateien vorgenommen haben, können Sie diese Ereignisse noch einmal über die Dataflow-Vorlage für die Migration im Modus retryDLQ ausführen.

Mit dem folgenden Befehl wird eine neue Dataflow-Pipeline gestartet, in der nur die Elemente in der Dead-Letter-Warteschlange verarbeitet werden:

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

Nächste Schritte

Zurück zu Zu Firestore mit MongoDB-Kompatibilität migrieren