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 abgerufen, wie die Anfrage zum Erstellen des Verbindungsprofils aussieht:

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

Sie können Datastream-Verbindungsprofile 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 einem Datastream-Stream

Wenn Sie einen Datenstream 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 wird mit dem folgenden gcloud CLI-Befehl nach Details zur Anfrage zum Erstellen des Streams gesucht:

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

Behebung von wiederholbaren Fehlern

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 in Cloud Storage eingesehen werden. Rufen Sie dazu den Pfad auf, der in der Umgebungsvariable DLQ_LOCATION 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

Fehlerbehebung bei nicht wiederholbaren Fehlern

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

  1. Rufen Sie den Cloud Storage-Speicherort auf, der in der Umgebungsvariable DLQ_LOCATION angegeben ist.

  2. Maximieren Sie die Ordner im Baum der verschachtelten Ordner, der anhand der Zeitstempel erstellt wurde, um die neuesten Inhalte in der Warteschlange zu sehen. Die Dateien könnten in Shards aufgeteilt worden sein und wie im folgenden Beispiel aussehen:

    Dateien in der DLQ

  3. 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 des ursprünglichen Ereignisses und die aufgetretene 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.

  4. 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 Longs sind.

  • Dokumente, die das Firestore-Limit von 16 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 wieder an denselben Cloud Storage-Speicherort hochladen, um die Originaldatei zu überschreiben. 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