Resolver problemas nas transferências de sistema de arquivos

Neste documento, descrevemos como solucionar problemas de transferência e de agente e como encontrar registros do agente para ajudá-lo a solucionar problemas.

Erros

A tabela a seguir descreve as mensagens de erros de transferência e como resolvê-los:

Mensagem de erro Tipo de erro O que o erro significa Como resolver o erro
Modificado durante a transferência FILE_MODIFIED_FAILURE O arquivo de origem é modificado durante a transferência sempre que o Serviço de transferência do Cloud Storage tentava copiar o arquivo de origem. Evite gravações no arquivo especificado durante a próxima operação do Serviço de transferência do Cloud Storage.
Falha ao transferir PRECONDITION_FAILURE O objeto do Cloud Storage associado ao arquivo de origem foi modificado sempre que o Serviço de transferência do Cloud Storage tentou fazer upload do arquivo. Ao criar jobs de transferência, use prefixos de objeto exclusivos do Cloud Storage para impedir que vários jobs de transferência gravem o mesmo arquivo no mesmo bucket do Cloud Storage.
Diretório de origem não encontrado SOURCE_DIR_NOT_FOUND O caminho de origem especificado está incorreto ou está correto, mas nem todos os agentes têm acesso a ele. Verifique a configuração do job de transferência e certifique-se de que:
Não foi possível encontrar o diretório de origem ou de destino do job ROOT_DIR_NOT_FOUND O caminho de origem/destino especificado está incorreto ou está correto, mas nem todos os agentes têm acesso a ele. Verifique a configuração do job de transferência e certifique-se de que:
Arquivo não encontrado FILE_NOT_FOUND_FAILURE O arquivo de origem foi encontrado, mas foi excluído antes de ser transferido para o Cloud Storage. Se o arquivo foi excluído por engano, restaure-o para que o próximo job de transferência possa fazer o upload.
Falha ao encontrar o bucket de destino BUCKET_NOT_FOUND O bucket de destino não existe no Cloud Storage. Verifique se o nome do bucket de destino está correto e se ele existe.
Falha ao encontrar um objeto de metadados interno METADATA_OBJECT_
NOT_FOUND_FAILURE		 O Storage Transfer Service armazena metadados no bucket de destino com o prefixo storage-transfer. Esse erro será exibido se os arquivos de metadados forem excluídos antes da conclusão das operações de transferência correspondentes. Evite excluir objetos com o prefixo storage-transfer/ no bucket de destino até que todos os jobs de transferência sejam concluídos.
Falha devido a um nome de arquivo inválido INVALID_FILE_NAME O caminho de um arquivo de origem é inválido. Verifique e corrija o caminho do arquivo especificado. Verifique se o caminho usa caracteres compatíveis com o Cloud Storage.
Falha devido a uma classe de armazenamento inválida INVALID_FILE_STORAGE_CLASS A classe de armazenamento da origem não permite leituras. Encontre a documentação do seu provedor de nuvem para determinar como colocar os dados em uma classe de armazenamento que permita copiar os dados.
Falha devido a um URI de sessão de upload retomável inválido SESSION_URI_INVALID O ID do upload retomável ou o URI da sessão expirou ou foi cancelado. As novas tentativas estão sendo executadas incorretamente. Entre em contato com o suporte.
Falha devido a um tamanho de arquivo inválido INVALID_FILE_SIZE O tamanho do arquivo é inválido. Verifique se o tamanho do arquivo é maior ou igual a 0 e menor ou igual a 5 TiB (tamanho máximo do objeto do Cloud Storage) para transferências no Cloud Storage.
Falha devido a permissões PERMISSION_FAILURE e UNAUTHENTICATED Um agente de transferência não tinha permissões suficientes para executar uma operação. Há duas possibilidades para esse erro:
  • Um agente não tinha permissões suficientes do Google Cloud.
  • Um agente não conseguiu ler um arquivo ou diretório devido a permissões insuficientes no sistema de arquivos de origem.

Confirme o seguinte:
O objeto está sujeito à política de retenção do bucket e não pode ser excluído, substituído ou arquivado PERMISSION_FAILURE O bucket tem uma política de retenção em vigor e o objeto já existe. O Storage Transfer Service não pode substituir os objetos existentes no bucket. Esse erro pode ser exibido se o arquivo tiver mudado na origem ou se o Serviço de transferência do Cloud Storage tentar fazer o upload duas vezes devido a condições de rede e o primeiro upload for bem-sucedido. Verifique se os dados no seu bucket do Cloud Storage correspondem às suas expectativas. Confirme se o tamanho e o horário modificados (mtime) dos arquivos de origem correspondem aos equivalentes do objeto do Cloud Storage executando novamente o job e confirmando que não há erros.
O serviço não tinha permissões suficientes SERVICE_PERMISSION_FAILURE O Serviço de transferência do Cloud Storage não tinha permissões suficientes para executar uma operação. O Serviço de transferência do Cloud Storage usa uma conta de serviço gerenciada pelo Google, normalmente no formato project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com, para acessar recursos. Para determinar o PROJECT_NUMBER específico, use a chamada de API googleserviceaccounts.get. Verifique se a conta de serviço tem os seguintes papéis:
  • roles/storagetransfer.serviceAgent para o projeto
  • roles/storage.admin para todos os buckets de destino.
Agente incompatível AGENT_UNSUPPORTED_VERSION A versão do agente não é mais compatível com o Serviço de transferência do Cloud Storage. Esse erro é temporário e está relacionado a uma atualização inválida do agente. Se ocorrer, faça o seguinte:
  1. Interrompa todos os agentes.
  2. Extraia a imagem mais recente do docker executando: sudo docker pull gcr.io/cloud-ingest/tsop-agent
  3. Emita o comando Docker run para iniciar todos os contêineres do agente.
Se o problema persistir, entre em contato com a equipe de suporte.
Falha devido a incompatibilidade de hash HASH_MISMATCH_FAILURE Sempre que o Serviço de transferência do Cloud Storage tentava fazer upload desse arquivo, os bytes enviados eram corrompidos. Isso fez com que o hash do arquivo local não correspondesse ao hash do objeto resultante do Cloud Storage. Esse erro pode ser causado por uma série de possíveis problemas. Se você vir uma pequena porcentagem de falhas de incompatibilidade de hash (menos de 1%) em uma transferência grande, repita os arquivos com falha. Se você encontrar uma grande porcentagem de falhas de incompatibilidade de hash (1% ou mais), investigue possíveis falhas de memória, CPU ou outras falhas de hardware na máquina do agente.
Falha devido a um modo de arquivo incompatível UNSUPPORTED_FILE_MODE O Serviço de transferência do Cloud Storage encontrou um arquivo com um modo incompatível, como um dispositivo, um soquete, um pipe nomeado ou um arquivo irregular. Remova esses tipos de arquivo especiais do diretório de origem.
Falha devido a um erro no sistema de arquivos FILESYSTEM_ERROR Um agente encontrou um erro de sistema de arquivos ou sistema operacional ao executar uma operação do sistema de arquivos, como leitura, busca ou estatística. Leia a descrição da falha para entender qual operação do sistema de arquivos falhou. Verifique se o sistema de arquivos pode ser acessado pelo agente local e responsivo a operações básicas de arquivos
Falha devido a um erro desconhecido UNKNOWN_FAILURE Ocorreu um erro inesperado. Leia a descrição da falha. Se a descrição da falha não tiver informações suficientes para resolver o problema, entre em contato com o suporte.
Falha devido a uma especificação inválida INVALID_SPEC O agente recebeu uma especificação interna corrompida. Verifique os dados corrompidos nos hosts de agentes e entre em contato com o suporte se você não encontrar nenhum.
Falha devido a um arquivo de manifesto vazio ou inválido CONFORMANCE_FAILURE O agente não pode ler ou receber bytes CSV válidos devido à formatação inválida ou a entradas em CSV. Verifique se as entradas do manifesto são caminhos de arquivo válidos. Se a descrição da falha não tiver informações suficientes para resolver o problema, entre em contato com o suporte.
Estamos voltando a usar os uploads retomáveis em vez de uploads de várias partes devido a um erro de permissão negada PERMISSION_FAILURE Os uploads de várias partes foram ativados para esta transferência, mas as permissões corretas não foram definidas no bucket. Consulte a seção Uploads em várias partes de Permissões do sistema de arquivos para ver as permissões necessárias.

Como visualizar registros do agente

Os registros do agente contêm informações relevantes para os processos do agente e podem ajudar a solucionar problemas de conexão no agente. Se os agentes estiverem listados como conectados no Console do Google Cloud e você estiver enfrentando falhas de transferência, consulte Como visualizar erros para ver uma amostra de erros de transferência. Para visualizar registros com todos os arquivos do serviço de transferência do Cloud Storage considerados durante uma transferência, consulte Como visualizar registros de transferência.

Por padrão, os registros do agente são armazenados em /tmp. É possível alterar o local com a opção de linha de comando --log-dir=logs-directory.

Os registros são chamados de:

agent.hostname.username.log.log-level.timestamp

Em que:

  • hostname: nome do host onde o agente está sendo executado.
  • username: nome do usuário que executa o agente.
  • log-level é um dos seguintes:
    • INFO: mensagens informativas
    • ERROR: erros encontrados durante a transferência, mas que não impedem a continuação do job de transferência.
    • FATAL: erros encontrados que impedem a continuidade do job de transferência.
  • timestamp: carimbo de data/hora no formato YYYYMMDD-hhmmss.thread-id.

O diretório de registros contém links simbólicos para os registros mais recentes de cada um dos níveis de prioridade:

  • agent.ERROR
  • agent.FATAL
  • agent.INFO

Velocidade de transferência lenta

Se a transferência dos seus dados estiver demorando muito, verifique o seguinte:

  1. A capacidade de leitura do seu sistema de arquivos deve ser aproximadamente 1,5 vez a velocidade de upload desejada. É possível usar o FIO para testar a capacidade de leitura do seu sistema de arquivos.

    Instale o fio:

     sudo apt install -y fio

    Crie um novo diretório fiotest:

     TEST_DIR=/mnt/mnt_dir/fiotest
 sudo mkdir -p $TEST_DIR

    Teste a capacidade de leitura:

     sudo fio --directory=$TEST_DIR --direct=1
    --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
    --time_based=1 --runtime=180 --name=read_test --size=1G

    Depois de executar os comandos acima, o Fio gera um relatório. A linha denominada "bw" representa a largura de banda agregada total de todas as linhas de execução e pode ser usada como um proxy para capacidade de leitura.

  2. Use iPerf3 para verificar a largura de banda da Internet disponível para o Serviço de transferência do Cloud Storage.

  3. Cada agente de transferência precisa ter pelo menos 4 vCPUs e 8 GB de RAM.

Se você verificou as condições acima e ainda está com tempos de transferência longos, é possível adicionar outros agentes para aumentar o número de conexões simultâneas no sistema de arquivos dos seus dados.

Para mais informações sobre como maximizar o desempenho dos seus agentes de transferência, consulte Práticas recomendadas para agentes.

Solução de problemas de erros do agente

As seções a seguir descrevem como resolver problemas e resolver erros do agente de transferência:

Os agentes não estão conectados

Se os agentes de transferência não aparecerem como conectados no Console do Google Cloud:

  1. Verifique se os agentes podem se conectar às APIs do Cloud Storage:

    1. Execute o comando a seguir na mesma máquina que o agente de transferência para testar a conexão do agente com as APIs Cloud Storage:

      gcloud storage cp test.txt gs://my-bucket

      Substitua:

      my-bucket pelo nome do bucket do Cloud Storage.

  2. Se o projeto usa o VPC Service Controls, visualize os registros do agente para ver se há erros. Se o VPC Service Controls estiver mal configurado, os registros do agente INFO conterão o erro a seguir:

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    Nesta saída:

Os agentes estão conectados, mas os jobs falham

Se os agentes forem exibidos como conectados, mas os jobs de transferência falharem, verifique os detalhes de erro dos jobs com falha.

O proxy rejeita endereços IP

Se você executar por trás de um proxy como o Squid e usar uma lista de permissões, as solicitações poderão ser negadas porque endereços IP estão sendo usados em vez de nomes de host.

Para resolver esse problema, use o comando docker run para executar os agentes e adicione a seguinte flag:

--transfer-service-endpoint=storagetransfer.googleapis.com:443

Se você usar um endpoint alternativo para acessar googleapis.com (por exemplo, para o Private Service Connect), substitua googleapis.com pelo endpoint alternativo.