Esta página foi traduzida pela API Cloud Translation.

Usar registros de plataforma para resolver problemas com tópicos de importação do Cloud Storage

Este guia explica como usar os registros da plataforma do Google Cloud para resolver problemas ao usar tópicos de importação do Cloud Storage para ingerir dados.

Sobre a falha de transferência em tópicos de importação do Cloud Storage

Os tópicos de importação do Cloud Storage podem encontrar problemas que impedem a ingestão de dados. Por exemplo, ao usar um tópico de importação do Cloud Storage, você pode ter problemas para processar um objeto do Cloud Storage ou parte dele.

A lista a seguir descreve os motivos da falha de ingestão nos tópicos de importação do Cloud Storage que geram registros da plataforma:

Tamanho da mensagem
- As mensagens individuais não podem ter mais de 10 MB. Se forem, a mensagem inteira será ignorada.
- Se você estiver usando o formato Avro ou o formato Avro do Pub/Sub, os blocos de mensagens não poderão ter mais de 16 MB. Os blocos de mensagens maiores são ignorados.
Atributos da mensagem
- As mensagens podem ter no máximo 100 atributos. Qualquer atributo extra é descartado quando a mensagem é processada.
- As chaves de atributo não podem ter mais de 256 bytes e os valores não podem ter mais de 1.024 bytes. Chaves ou valores maiores são removidos da mensagem quando ela é processada.
  
  Para mais informações sobre as diretrizes para usar chaves e atributos de mensagem, consulte Usar atributos para publicar uma mensagem.
Formatação do Avro
- Verifique se os objetos Avro estão formatados corretamente. A formatação incorreta impede a ingestão da mensagem.
Formato de dados
- Verifique se você está usando uma versão do Avro com suporte. Os formatos sem suporte não são processados.

Sobre os registros da plataforma

Um serviço compatível do Google Cloud gera o próprio conjunto de registros de plataforma, capturando eventos e atividades relevantes para a operação desse serviço. Esses registros da plataforma contêm informações detalhadas sobre o que está acontecendo em um serviço, incluindo operações bem-sucedidas, erros, avisos e outros eventos importantes.

Os registros da plataforma fazem parte do Cloud Logging e compartilham os mesmos recursos. Confira a seguir uma lista de recursos importantes para registros de plataforma:

Os registros geralmente são estruturados como objetos JSON que permitem mais consultas e filtragem.
É possível conferir os registros da plataforma usando o Registro no console.
Os registros da plataforma também podem ser integrados ao Cloud Monitoring e a outras ferramentas de monitoramento para criar painéis, alertas e outros mecanismos de monitoramento.
O armazenamento de registros gera custos com base no volume ingerido e no período de retenção.

Para mais informações sobre os registros da plataforma, consulte Registros da plataforma do Google Cloud.

Papéis e permissões necessárias para usar os registros da plataforma

Antes de começar, verifique se você tem acesso ao Logging. Você precisa do papel (roles/logging.viewer) do Identity and Access Management (IAM) Visualizador de registros. Para mais informações sobre o acesso ao Logging, consulte Controle de acesso com o IAM.

Veja a seguir como verificar e conceder o acesso ao IAM:

Veja o acesso atual para verificar o acesso que cada principal tem.
Conceda um papel aos principais relevantes do projeto.

Ativar registros da plataforma

Os registros da plataforma ficam desativados por padrão para tópicos de importação. É possível ativar os registros da plataforma ao criar ou atualizar um tópico de importação do Cloud Storage.

Para desativar os registros da plataforma, atualize o tópico de importação do Cloud Storage.

Ativar os registros da plataforma ao criar um tópico de importação do Cloud Storage

Verifique se você concluiu os pré-requisitos para criar um tópico de importação do Cloud Storage.

Para criar um tópico de importação do Cloud Storage com os registros da plataforma ativados, siga estas etapas:

Console

No console do Google Cloud, acesse a página Tópicos.

Acesse Tópicos
Selecione Criar tópico.
A página de detalhes do tópico é aberta.
No campo ID do tópico, insira um ID para o tópico de importação do Cloud Storage.
Para mais informações sobre como nomear tópicos, consulte as diretrizes de nomenclatura.
Selecione Adicionar uma assinatura padrão.
Selecione Ativar ingestão.
Especifique as opções de transferência seguindo as instruções em Criar um tópico de importação do Cloud Storage.
Selecione Ativar registros da plataforma.
Mantenha as outras configurações padrão.
Selecione Criar tópico.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Para ativar os registros da plataforma, verifique se a flag --ingestion-log-severity está definida como WARNING ou mais recente. Execute o comando gcloud pubsub topics create:
```
gcloud pubsub topics create TOPIC_ID\
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --ingestion-log-severity=WARNING
```
Substitua:
- TOPIC_ID: o nome ou ID do tópico.
- BUCKET_NAME: especifica o nome de um bucket Por exemplo, prod_bucket. O nome do bucket não pode incluir o ID do projeto. Para criar um bucket, consulte Criar buckets.
- INPUT_FORMAT: especifica o formato dos objetos que são ingeridos. Os valores podem ser text, avro ou pubsub_avro. Para mais informações sobre essas opções, consulte Formato de entrada.

Se você tiver problemas, consulte Solução de problemas em um tópico de importação do Cloud Storage.

Ativar os registros da plataforma ao atualizar um tópico de importação do Cloud Storage

Siga as etapas abaixo:

Console

No console do Google Cloud, acesse a página Tópicos.

Acesse Tópicos
Clique no tópico de importação do Cloud Storage.
Na página de detalhes do tópico, clique em Editar.
Selecione Ativar registros da plataforma.
Clique em Atualizar.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Para não perder as configurações do tópico de importação, inclua todas elas sempre que atualizar o tópico. Se você deixar algo de fora, o Pub/Sub vai redefinir a configuração para o valor padrão original.

Para ativar os registros da plataforma, verifique se a variável ingestion-log-severity está definida como WARNING. Execute o comando gcloud pubsub topics update com todas as flags mencionadas no exemplo a seguir:
```
gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=WARNING
```
Substitua:
- TOPIC_ID é o ID ou nome do tópico. Não é possível atualizar este campo.
- BUCKET_NAME: especifica o nome de um bucket Por exemplo, prod_bucket. O nome do bucket não pode incluir o ID do projeto.
- INPUT_FORMAT: especifica o formato dos objetos que são ingeridos. Os valores podem ser text, avro ou pubsub_avro. Para mais informações sobre essas opções, consulte Formato de entrada.
- TEXT_DELIMITER: especifica o delimitador para dividir objetos de texto em mensagens do Pub/Sub. Ele precisa ser um único caractere e só pode ser definido quando INPUT_FORMAT for text. O padrão é o caractere de nova linha (\n).
  
  Ao usar a CLI gcloud para especificar o delimitador, preste atenção ao processamento de caracteres especiais, como o \n de nova linha. Use o formato '\n' para garantir que o delimitador seja interpretado corretamente. Basta usar \n sem aspas ou escapar dos resultados em um delimitador de "n".
- MINIMUM_OBJECT_CREATE_TIME: especifica o tempo mínimo em que um objeto foi criado para ser transferido. Ele precisa estar no formato UTC YYYY-MM-DDThh:mm:ssZ. Por exemplo, 2024-10-14T08:30:30Z.
  
  Qualquer data, passada ou futura, de 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z, é válida.
- MATCH_GLOB: especifica o padrão de glob a ser correspondido para que um objeto seja ingerido. Ao usar a CLI gcloud, um glob de correspondência com caracteres * precisa ter o caractere * formatado como escape no formulário \*\*.txt ou o glob de correspondência inteiro precisa estar entre aspas "**.txt" ou '**.txt'. Para informações sobre a sintaxe com suporte para padrões glob, consulte a documentação do Cloud Storage.

Desativar registros da plataforma

Siga as etapas abaixo:

Console

No console do Google Cloud, acesse a página Tópicos.

Acesse Tópicos
Clique no tópico de importação do Cloud Storage.
Na página de detalhes do tópico, clique em Editar.
Desmarque Ativar registros da plataforma.
Clique em Atualizar.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Para não perder as configurações do tópico de importação, inclua todas elas sempre que atualizar o tópico. Se você deixar algo de fora, o Pub/Sub vai redefinir a configuração para o valor padrão original.

Para desativar os registros da plataforma, verifique se a flag ingestion-log-severity está definida como DISABLED. Execute o comando gcloud pubsub topics update com todas as flags mencionadas no exemplo a seguir:
```
gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=DISABLED
```
Substitua:
- TOPIC_ID é o ID ou nome do tópico. Não é possível atualizar este campo.
- BUCKET_NAME: especifica o nome de um bucket Por exemplo, prod_bucket. O nome do bucket não pode incluir o ID do projeto.
- INPUT_FORMAT: especifica o formato dos objetos que são ingeridos. Os valores podem ser text, avro ou pubsub_avro. Para mais informações sobre essas opções, consulte Formato de entrada.
- TEXT_DELIMITER: especifica o delimitador para dividir objetos de texto em mensagens do Pub/Sub. Ele precisa ser um único caractere e só pode ser definido quando INPUT_FORMAT for text. O padrão é o caractere de nova linha (\n).
  
  Ao usar a CLI gcloud para especificar o delimitador, preste atenção ao processamento de caracteres especiais, como o \n de nova linha. Use o formato '\n' para garantir que o delimitador seja interpretado corretamente. Basta usar \n sem aspas ou escapar dos resultados em um delimitador de "n".
- MINIMUM_OBJECT_CREATE_TIME: especifica o tempo mínimo em que um objeto foi criado para ser transferido. Ele precisa estar no formato UTC YYYY-MM-DDThh:mm:ssZ. Por exemplo, 2024-10-14T08:30:30Z.
  
  Qualquer data, passada ou futura, de 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z, é válida.
- MATCH_GLOB: especifica o padrão de glob a ser correspondido para que um objeto seja ingerido. Ao usar a CLI gcloud, um glob de correspondência com caracteres * precisa ter o caractere * formatado como escape no formulário \*\*.txt ou o glob de correspondência inteiro precisa estar entre aspas "**.txt" ou '**.txt'. Para informações sobre a sintaxe com suporte para padrões glob, consulte a documentação do Cloud Storage.

Conferir os registros da plataforma

Para conferir os registros da plataforma para o tópico de importação do Cloud Storage, faça o seguinte:

Console do Google Cloud

No Console do Google Cloud, acesse o Explorador de registros.

Acessar o Explorador de registros
Selecione um projeto do Google Cloud.
Se necessário, no menu Upgrade, alterne de Visualizador de registros legado para Explorador de registros.
Para filtrar seus registros e mostrar apenas entradas para temas de importação do Cloud Storage, digite resource.type="resource.type=pubsub_topic AND severity=WARNING no campo de consulta e clique em Executar consulta.
No painel Resultados da consulta, clique em Editar hora para alterar o período de retorno dos resultados.

Para mais informações sobre como usar o Explorador de registros, consulte Como usar o Explorador de registros.

CLI da gcloud

Para usar a CLI gcloud para pesquisar registros da plataforma para tópicos de importação do Cloud Storage, use o comando gcloud logging read.

Especifique um filtro para limitar os resultados aos registros da plataforma para tópicos de importação do Cloud Storage.

gcloud logging read "resource.type=pubsub_topic AND severity=WARNING"

API Cloud Logging

Use o método entries.list da API Cloud Logging.

Para filtrar os resultados e incluir apenas registros da plataforma para tópicos de importação do Cloud Storage, use o campo filter. Confira a seguir um exemplo de objeto de solicitação JSON.

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"pubsub_topic\" AND severity=WARNING"
}

Conferir e entender o formato de registro da plataforma

A seção a seguir inclui exemplos de registros da plataforma e descreve os campos para registros da plataforma.

Todos os campos específicos do registro da plataforma estão contidos em um objeto jsonPayload.

Falha no Avro

{
  "insertId": "1xnzx8md4768",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "objectGeneration": "1661148924738910",
      "bucket": "bucket_in_avro_format",
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "avroFailureReason": {}
    },
    "topic": "projects/interpod-p2-management/topics/avro_bucket_topic",
    "errorMessage": "Unable to parse the header of the object. The object won't be ingested."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "project_id": "interpod-p2-management",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}

Campo de registro	Descrição
`insertId`	Um identificador exclusivo da entrada de registro.
`jsonPayload.@type`	Identifica o tipo de evento. Sempre `type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`.
`jsonPayload.cloudStorageFailure.objectGeneration`	O número de geração do objeto do Cloud Storage.
`jsonPayload.cloudStorageFailure.bucket`	O bucket do Cloud Storage que contém o objeto.
`jsonPayload.cloudStorageFailure.objectName`	O nome do objeto do Cloud Storage.
`jsonPayload.cloudStorageFailure.avroFailureReason`	Contém detalhes mais específicos do erro de análise do Avro. Este campo é deixado em branco.
`jsonPayload.topic`	O tópico do Pub/Sub para o qual a mensagem foi destinada.
`jsonPayload.errorMessage`	Uma mensagem de erro legível por humanos.
`resource.type`	O tipo de recurso. Sempre `pubsub_topic`.
`resource.labels.project_id`	O ID do projeto do Google Cloud.
`resource.labels.topic_id`	O ID do tópico do Pub/Sub.
`timestamp`	Carimbo de data/hora de geração da entrada de registro.
`severity`	Nível de gravidade, que é `WARNING`.
`logName`	Nome do registro.
`receiveTimestamp`	Carimbo de data/hora de recebimento da entrada de registro.

Falha de texto

{
  "insertId": "1kc4puoag",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "bucket": "bucket_in_text_format",
      "apiViolationReason": {},
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "objectGeneration": "1727990048026758"
    },
    "topic": "projects/interpod-p2-management/topics/large_text_bucket_topic",
    "errorMessage": "The message has exceeded the maximum allowed size of 10000000 bytes. The message won't be published."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "large_text_bucket_topic",
      "project_id": "interpod-p2-management"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}

Campo de registro	Descrição
`insertId`	Um identificador exclusivo da entrada de registro.
`jsonPayload.@type`	Identifica o tipo de evento. Sempre `type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`.
`jsonPayload.cloudStorageFailure.objectGeneration`	O número de geração do objeto do Cloud Storage.
`jsonPayload.cloudStorageFailure.bucket`	O bucket do Cloud Storage que contém o objeto.
`jsonPayload.cloudStorageFailure.objectName`	O nome do objeto do Cloud Storage.
`jsonPayload.cloudStorageFailure.apiViolationReason`	Contém detalhes sobre a violação da API. Este campo é deixado em branco.
`jsonPayload.topic`	O tópico do Pub/Sub.
`jsonPayload.errorMessage`	Uma mensagem legível.
`resource.type`	Tipo de recurso, sempre `pubsub_topic`.
`resource.labels.project_id`	ID do projeto do Google Cloud.
`resource.labels.topic_id`	ID do tópico do Pub/Sub.
`timestamp`	Carimbo de data/hora da geração da entrada de registro.
`severity`	Nível de gravidade, que é `WARNING`.
`logName`	Nome do registro.
`receiveTimestamp`	Hora em que a entrada de registro foi recebida pelo Logging.