Resolução de problemas de migração
Esta secção fornece sugestões para resolver problemas comuns que podem surgir quando cria e gere pipelines de fluxo de dados e fluxo de dados.
Resolução de problemas de um perfil de ligação do fluxo de dados
O procedimento de migração requer que crie dois perfis de ligação do Datastream: um para ler dados da base de dados compatível com o MongoDB de origem e outro para escrever os dados num contentor do Cloud Storage.
Estes passos usam o comando gcloud datastream connection-profiles create.
Quando cria um perfil de associação da stream de dados com este comando, devolve metadados semelhantes ao seguinte exemplo:
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
Pode usar o identificador realçado que começa por operation- para obter
o estado da operação de stream de dados especificada. Para o exemplo de saída acima, o seguinte comando da CLI gcloud obtém detalhes sobre o pedido de criação do perfil de ligação:
gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"
Pode examinar os perfis de ligação da stream de dados e outros artefactos da stream de dados na Google Cloud consola.
Na Google Cloud consola, aceda à página Fluxo de dados:
Resolução de problemas de uma stream de dados
Quando cria uma stream de dados com o comando gcloud datastream streams create, são devolvidos metadados semelhantes ao seguinte exemplo:
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
Pode usar o identificador realçado que começa por operation- para obter
o estado da operação de stream de dados especificada. Para o exemplo de saída acima, o seguinte comando da CLI gcloud obtém detalhes sobre o pedido de criação de streams:
gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"
Para procurar o estado de uma stream existente, use:
gcloud datastream streams describe $DATASTREAM_NAME --location=$LOCATION
Pode examinar as streams de dados e outros artefactos de streams de dados na Google Cloud consola.
Na Google Cloud consola, aceda à página Fluxo de dados:
Resolução de problemas do pipeline do Dataflow
Pode monitorizar a execução do pipeline do Dataflow na Google Cloud consola.
Na Google Cloud consola, aceda à página Fluxo de dados:
Resolução de problemas de erros repetíveis
Os erros repetíveis são erros momentâneos que acabam por ter êxito. Os erros comuns repetíveis são:
- Problemas de rede ou conetividade
- Concorrência de transações
- Ligações fechadas devido ao equilíbrio de carga
Os documentos que não puderam ser escritos no destino devido a erros são armazenados no contentor do Cloud Storage, na localização especificada pelo parâmetro deadLetterQueueDirectory do modelo do Dataflow.
Por predefinição, as tentativas de erros repetíveis são feitas até ao número de vezes especificado pelo parâmetro dlqMaxRetryCount.
Pode inspecionar diretamente a fila de mensagens rejeitadas (DLQ) a partir do Cloud Storage navegando para o caminho especificado na variável de ambiente DLQ_LOCATION . O caminho vai conter uma hierarquia de pastas com data/hora, que contêm registos JSON de documentos e atualizações que não foi possível escrever na base de dados do Firestore com compatibilidade com o MongoDB.
Partindo do princípio de que a fila de mensagens rejeitadas só contém documentos que falharam devido a erros repetíveis, pode tentar esvaziar a fila executando o modelo do Dataflow num modo que só opere nesta fila.
Para tal, defina o parâmetro runMode como retryDLQ, conforme mostrado no seguinte exemplo:
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
Resolução de problemas relacionados com erros não repetíveis
Os erros não repetíveis comuns são:
- Tipos BSON não suportados
- Tipos BSON não suportados usados como
_id - 0L não suportado como
_id - Tamanhos de documentos superiores ao limite de 4 MB do Firestore
Os erros não repetíveis são armazenados no contentor do Cloud Storage, na localização especificada pelo parâmetro deadLetterQueueDirectory do modelo do Dataflow.
Examinar a fila de mensagens rejeitadas (DLQ)
Depois de todo o processamento ter parado, o que significa que não está a ser processado tráfego ativo e não estão a ser repetidos eventos com erros, os eventos com erros são mantidos no Cloud Storage.
Pode verificar se o processamento foi interrompido inspecionando os eventos de gravação transacional e confirmando que não existe débito de processamento e que não estão a ser geradas novas entradas de registo.
Pode inspecionar a DLQ diretamente a partir do Cloud Storage:
- Navegue para a localização do Cloud Storage especificada na variável de ambiente DLQ_LOCATION.
Na árvore de pastas aninhadas construída de acordo com as indicações de tempo, expanda as pastas para ver o conteúdo mais recente na fila. Os ficheiros podem ter sido divididos e ter um aspeto semelhante ao seguinte exemplo:
Inspecione cada ficheiro para ver os documentos e as atualizações que não foram aplicados à base de dados de destino. Cada mensagem vai conter um payload do evento original e da exceção que ocorreu.
Existe uma possibilidade muito baixa de existirem erros repetíveis, especialmente se tiver sido usado um valor baixo para o parâmetro
dlqMaxRetryCount, mas, geralmente, os eventos que acabam na DLQ não são repetíveis pelos motivos descritos anteriormente.Pode optar por anular a migração e retomar o tráfego da aplicação para a base de dados de origem, resolvendo as restrições de dados do Firestore na base de dados de origem e executando novamente todo o processo de migração. Em alternativa, pode resolver os problemas de dados com cada evento DLQ e tentar novamente o processamento destes eventos.
Para cada linha em cada ficheiro DLQ, pode:
Converta os tipos de dados não suportados num tipo de dados alternativo editando o payload do documento. A carga útil do documento está no formato JSON estendido canónico. Expresse o novo tipo de dados no formato JSON canónico estendido.
Reatribua o documento 0L
_ida um novo Long ou a um tipo de dados diferente, como String. A reatribuição a um tipo de dados diferente pode exigir alterações à lógica da aplicação se as expetativas de código existentes forem que os_idsão todos Longs.Os documentos que excedem o limite de 4 MB do Firestore podem ser separados em documentos mais pequenos ou o respetivo conteúdo pode ser comprimido. No entanto, isto requer alterações à lógica da aplicação para processar os dados.
Ignorar o evento eliminando a linha do ficheiro DLQ.
Para modificar os ficheiros DLQ, tem de transferir os ficheiros .json localmente, modificar o conteúdo e carregá-los novamente para a mesma localização do Cloud Storage, substituindo o ficheiro original. Se todos os documentos referenciados no ficheiro puderem ser excluídos em segurança da migração, o ficheiro completo pode ser eliminado.
Depois de fazer as modificações aos ficheiros DLQ, pode executar novamente estes eventos através do modelo do Dataflow de migração no modo retryDLQ.
O comando seguinte inicia um novo pipeline do Dataflow que só processa os itens na fila de mensagens rejeitadas:
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