Solução de problemas de migração
Nesta seção, você encontra dicas para solucionar problemas comuns que podem surgir ao criar e gerenciar pipelines do Datastream e do Dataflow.
Resolver problemas de um perfil de conexão do Datastream
O procedimento de migração exige a criação de dois perfis de conexão do Datastream: um para leitura de dados do banco de dados de origem compatível com MongoDB e outro para gravação dos dados em um bucket do Cloud Storage.
Estas etapas usam o comando gcloud datastream connection-profiles create.
Ao criar um perfil de conexão do Datastream com esse comando, ele retorna metadados semelhantes ao exemplo a seguir:
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
Use o identificador destacado que começa com operation- para recuperar
o status da operação do Datastream. Para o exemplo de saída acima, o seguinte comando da CLI gcloud recupera detalhes sobre a solicitação de criação do perfil de conexão:
gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"
É possível examinar perfis de conexão do Datastream e outros artefatos do Datastream no Google Cloud console.
No Google Cloud console, acesse a página Datastream:
Resolver problemas com um stream do Datastream
Ao criar um fluxo do Datastream com o comando
gcloud datastream streams create, ele retorna metadados semelhantes
ao exemplo a seguir:
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
Use o identificador destacado que começa com operation- para recuperar
o status da operação do Datastream. Para o exemplo de saída acima, o seguinte comando da CLI gcloud recupera detalhes sobre a solicitação de criação de stream:
gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"
Para consultar o status de um fluxo, use:
gcloud datastream streams describe $DATASTREAM_NAME --location=$LOCATION
É possível analisar os fluxos do Datastream e outros artefatos dele no console Google Cloud .
No Google Cloud console, acesse a página Datastream:
Solução de problemas do pipeline do Dataflow
É possível monitorar a execução do pipeline do Dataflow no console do Google Cloud .
No Google Cloud console, acesse a página Dataflow:
Como solucionar erros que permitem uma nova tentativa
Erros que permitem uma nova tentativa são erros transitórios que vão ser corrigidos. Os erros comuns que podem ser repetidos são:
- Problemas de rede ou conectividade
- Disputa de transações
- Conexões fechadas devido ao balanceamento de carga
Os documentos que não puderem ser gravados no destino devido a erros serão
armazenados no bucket do Cloud Storage, no local especificado pelo
parâmetro deadLetterQueueDirectory do modelo do Dataflow.
Por padrão, os erros que podem ser repetidos serão repetidos até o número de vezes especificado pelo parâmetro dlqMaxRetryCount.
A fila de mensagens não entregues (DLQ, na sigla em inglês) pode ser inspecionada diretamente no Cloud Storage. Para isso, acesse o caminho especificado na variável de ambiente DLQ_LOCATION. O caminho vai conter uma hierarquia de pastas com carimbo de data/hora, contendo registros JSON de documentos e atualizações que não puderam ser gravados no banco de dados do Firestore com compatibilidade com o MongoDB.
Supondo que a fila de mensagens não entregues contenha apenas documentos que falharam devido a erros que podem ser repetidos, tente esvaziar a fila executando o modelo do Dataflow em um modo que opere apenas nessa fila.
Para fazer isso, defina o parâmetro runMode como retryDLQ, conforme mostrado no exemplo a seguir:
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
Solução de problemas de erros que não aceitam novas tentativas
Os erros não repetíveis comuns são:
- Tipos de BSON sem suporte
- Tipos BSON não aceitos usados como
_id - 0L não compatível como
_id - Tamanhos de documentos maiores que o limite de 4 MB do Firestore
Os erros não repetíveis serão armazenados no bucket do Cloud Storage, no local especificado pelo parâmetro deadLetterQueueDirectory do modelo do Dataflow.
Como analisar a fila de mensagens inativas (DLQ)
Depois que todo o processamento é interrompido, o que significa que nenhum tráfego ativo está sendo processado e nenhum evento com erro está sendo repetido, os eventos com erro são mantidos no Cloud Storage.
Para verificar se o processamento foi interrompido, inspecione os eventos de gravação transacional e confirme que não há taxa de transferência de processamento e que novas entradas de registro não estão sendo geradas.
É possível inspecionar a DLQ diretamente no Cloud Storage:
- Navegue até o local do Cloud Storage especificado na variável de ambiente DLQ_LOCATION.
Na árvore de pastas aninhadas construída de acordo com os carimbos de data/hora, expanda as pastas para ver o conteúdo mais recente na fila. Os arquivos podem ter sido fragmentados e ter uma aparência semelhante ao exemplo a seguir:
Inspecione cada arquivo para ver os documentos e as atualizações que não foram aplicados ao banco de dados de destino. Cada mensagem vai conter um payload do evento original e da exceção que ocorreu.
É muito baixa a possibilidade de haver erros que podem ser repetidos, principalmente se um valor baixo foi usado para o parâmetro
dlqMaxRetryCount. No entanto, geralmente, os eventos que acabam na DLQ não podem ser repetidos pelos motivos descritos anteriormente.Você pode abortar a migração e retomar o tráfego de aplicativos para o banco de dados de origem, resolvendo as restrições de dados do Firestore no banco de dados de origem e executando novamente todo o processo de migração. Outra opção é resolver os problemas de dados com cada evento da DLQ e tentar processar esses eventos novamente.
Para cada linha em cada arquivo de DLQ, você pode:
Edite a payload do documento para converter os tipos de dados não aceitos em um tipo alternativo. O payload do documento estará no formato JSON canônico estendido. 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 mudanças na lógica do aplicativo se as expectativas de código atuais forem que todos os_idsejam Longs.Documentos que excedem o limite de 4 MB do Firestore podem ser separados em documentos menores ou ter o conteúdo compactado. No entanto, isso exigiria mudanças na lógica do aplicativo para processar os dados.
Ignore o evento excluindo a linha do arquivo da DLQ.
Para modificar os arquivos da DLQ, faça o download dos arquivos .json localmente, altere o conteúdo e faça upload novamente para o mesmo local do Cloud Storage, substituindo o arquivo original. Se todos os documentos referenciados no arquivo puderem ser excluídos com segurança da migração, o arquivo inteiro poderá ser excluído.
Depois de fazer as modificações nos arquivos da DLQ, é possível executar novamente esses
eventos usando o modelo de migração do Dataflow no modo
retryDLQ.
O comando a seguir inicia um novo pipeline do Dataflow que processa apenas os itens na fila de mensagens não entregues:
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