Use registos da plataforma para resolver problemas de tópicos de importação

Este guia explica como usar os registos da plataforma para resolver problemas quando usa tópicos de importação, incluindo o seguinte: tópicos de importação do Google Cloud Storage, tópicos de importação do Azure Event Hubs, tópicos de importação do Amazon MSK e tópicos de importação do Confluent Cloud. Google Cloud

Acerca dos registos da plataforma

Um serviço suportado Google Cloud gera o seu próprio conjunto de registos da plataforma, captando eventos e atividades relevantes para o funcionamento desse serviço. Estes registos da plataforma contêm informações detalhadas sobre o que está a acontecer num serviço, incluindo operações bem-sucedidas, erros, avisos e outros eventos dignos de nota.

Os registos da plataforma fazem parte do Cloud Logging e partilham as mesmas funcionalidades. Por exemplo, segue-se uma lista de funcionalidades importantes para os registos da plataforma:

  • Normalmente, os registos são estruturados como objetos JSON que permitem mais consultas e filtragem.

  • Pode ver os registos da plataforma através do registo na consola.

  • Os registos da plataforma também podem ser integrados com o Cloud Monitoring e outras ferramentas de monitorização para criar painéis de controlo, alertas e outros mecanismos de monitorização.

  • O armazenamento de registos incorre em custos com base no volume carregado e no período de retenção.

Para mais informações sobre os registos da plataforma, consulte o artigo Registos da Google Cloud Platform.

Antes de começar

Certifique-se de que concluiu os pré-requisitos para criar o tópico que está a usar:

Funções e autorizações necessárias

Antes de começar, verifique se tem acesso ao Logging. Precisa da função Visualizador de registos (roles/logging.viewer) Identity and Access Management (IAM). Para mais informações sobre o acesso ao registo, consulte o artigo Controlo de acesso com a IAM.

As seguintes descrições explicam como validar e conceder acesso ao IAM:

Acerca das falhas de carregamento de tópicos de importação

Os tópicos de importação podem encontrar problemas que impedem a ingestão bem-sucedida de dados.

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 bem-sucedida de dados. Por exemplo, quando usa um tópico de importação do Cloud Storage, pode ter problemas ao carregar um objeto do Cloud Storage ou parte de um objeto.

A lista seguinte descreve os motivos da falha na carregamento nos tópicos de importação do Cloud Storage que geram registos da plataforma:

  • Tamanho da mensagem

    • As mensagens individuais não podem ter mais de 10 MB. Se forem apresentados, toda a mensagem é ignorada.

    • Se estiver a usar o formato Avro ou Pub/Sub Avro, os blocos Avro não podem ter mais de 16 MB. Os blocos Avro maiores são ignorados.

  • Atributos de mensagens

    • As mensagens podem ter um máximo de 100 atributos. Todos os atributos adicionais são ignorados quando a mensagem é carregada.

    • As chaves de atributos não podem ter mais de 256 bytes e os valores não podem ter mais de 1024 bytes. Se o valor for superior ao tamanho máximo, o par chave-valor completo é ignorado na mensagem quando é carregado.

      Para mais informações acerca das diretrizes de utilização de chaves de mensagens e atributos, consulte o artigo Use atributos para publicar uma mensagem.

  • Formatação Avro

    • Certifique-se de que os objetos Avro estão formatados corretamente. A formatação incorreta impede o carregamento da mensagem.

  • Formato de dados

Tópicos de importação do Azure Event Hubs, Amazon MSK e Confluent Cloud

Os tópicos de importação do Azure Event Hubs, Amazon MSK e Confluent Cloud podem encontrar problemas que impedem a ingestão bem-sucedida de dados.

A lista seguinte descreve os motivos da falha de carregamento nos tópicos de importação que geram registos da plataforma:

  • Tamanho da mensagem

    • As mensagens individuais não podem ter mais de 10 MB. Se forem apresentados, toda a mensagem é ignorada.

  • Atributos de mensagens

    • As mensagens podem ter um máximo de 100 atributos. Todos os atributos adicionais são ignorados quando a mensagem é carregada.

    • As chaves de atributos não podem ter mais de 256 bytes e os valores não podem ter mais de 1024 bytes. Se o valor for superior ao tamanho máximo, o par chave-valor completo é ignorado na mensagem quando é carregado.

      Para mais informações acerca das diretrizes de utilização de chaves de mensagens e atributos, consulte o artigo Use atributos para publicar uma mensagem.

Ative os registos da plataforma

Os registos da plataforma estão desativados por predefinição para tópicos de importação. Pode ativar os registos da plataforma quando cria ou atualiza um tópico de importação. Para desativar os registos da plataforma, atualize o tópico de importação.

Ative os registos da plataforma ao criar um tópico de importação

Para ativar os registos da plataforma ao criar um tópico de importação, faça o seguinte:

Consola

  1. Na Google Cloud consola, aceda à página Tópicos.

    Aceda a Tópicos

  2. Clique em Criar tópico.

    É apresentada a página de detalhes do tópico.

  3. No campo ID do tópico, introduza um ID para o tópico de importação.

    Para mais informações sobre a atribuição de nomes a tópicos, consulte as diretrizes de nomenclatura.

  4. Selecione Adicionar uma subscrição predefinida.

  5. Selecione Ativar carregamento.

  6. Manter as outras predefinições.
  7. Clique em Criar tópico.

gcloud

  1. 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.

  2. Para ativar os registos da plataforma, certifique-se de que a flag --ingestion-log-severity está definida como WARNING ou um nível de gravidade inferior, como INFO ou DEBUG. Execute o comando gcloud pubsub topics create para o respetivo tópico que está a usar:

    Por exemplo, para ativar os registos da plataforma num tópico de importação do Cloud Storage, inclua a flag --ingestion-log-severity=WARNING no 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

Ative os registos da plataforma enquanto atualiza um tópico de importação

Para ativar os registos da plataforma quando atualiza um tópico de importação, faça o seguinte:

Consola

  1. Na Google Cloud consola, aceda à página Tópicos.

    Aceda a Tópicos

  2. Clique no tópico de importação respetivo que está a usar (tópico de importação do Cloud Storage, tópico de importação do Azure Event Hubs, tópico de importação do Amazon MSK ou tópico de importação do Confluent Cloud).

  3. Na página de detalhes do tópico, clique em Editar.

  4. Selecione Ativar registos da plataforma.

  5. Clique em Atualizar.

gcloud

  1. 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.

  2. Para ativar os registos da plataforma, certifique-se de que a gravidade do registo de carregamento está definida como WARNING ou um nível de gravidade inferior, como INFO ou DEBUG. Execute o comando gcloud pubsub topics update com todas as flags possíveis que especificam as definições do respetivo tópico que está a usar:

    Por exemplo, para atualizar os registos num tópico de importação do Cloud Storage existente, inclua a flag --ingestion-log-severity=WARNING no comando gcloud pubsub topics create e inclua todos os valores de flags possíveis que especificam as definições de um tópico de importação do Cloud Storage.

    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

Desative os registos da plataforma

Para desativar os registos da plataforma para o tópico de importação respetivo que está a usar, faça o seguinte:

Consola

  1. Na Google Cloud consola, aceda à página Tópicos.

    Aceda a Tópicos

  2. Clique no tópico de importação respetivo que está a usar (tópico de importação do Cloud Storage, tópico de importação do Azure Event Hubs, tópico de importação do Amazon MSK ou tópico de importação do Confluent Cloud).

  3. Na página de detalhes do tópico, clique em Editar.

  4. Desmarque a opção Ativar registos da plataforma.

  5. Clique em Atualizar.

gcloud

  1. 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.

  2. Para desativar os registos da plataforma, certifique-se de que a gravidade do registo de carregamento está definida como DISABLED. Execute o comando gcloud pubsub topics update com todas as flags possíveis que especificam as definições do respetivo tópico que está a usar:

    Por exemplo, para desativar os registos num tópico de importação do Cloud Storage existente, inclua a flag --ingestion-log-severity=DISABLED no comando gcloud pubsub topics update e inclua todas as flags possíveis que especificam definições para um tópico de importação do Cloud Storage.

    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

Veja os registos da plataforma

Para ver os registos da plataforma do tópico de importação respetivo que está a usar, faça o seguinte:

Google Cloud consola

  1. Na Google Cloud consola, aceda ao Explorador de registos.

    Aceda ao Explorador de registos

  2. Selecione um Google Cloud projeto.

  3. Se necessário, no menu Atualizar, mude do Visualizador de registos antigo para o Explorador de registos.

  4. Clique no botão Mostrar consulta.

  5. Para filtrar os seus registos de modo a mostrar apenas entradas para os respetivos tópicos de importação que está a usar (tópico de importação do Cloud Storage, tópico de importação do Azure Event Hubs, tópico de importação do Amazon MSK ou tópico de importação do Confluent Cloud), escreva "resource.type=pubsub_topic AND severity=WARNING" no campo de consulta e clique em Executar consulta.

  6. No painel Resultados da consulta, clique em Editar hora para alterar o período durante o qual devem ser devolvidos os resultados.

Para mais informações sobre a utilização do Explorador de registos, consulte o artigo Usar o Explorador de registos.

CLI gcloud

Para usar a CLI gcloud para pesquisar registos da plataforma para os respetivos tópicos de importação que está a usar, use o comando gcloud logging read.

Especifique um filtro para limitar os resultados aos registos da plataforma para os respetivos tópicos de importação que está a usar (tópico de importação do Cloud Storage, tópico de importação do Azure Event Hubs, tópico de importação do Amazon MSK ou tópico de importação do Confluent Cloud).

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

Cloud Logging API

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

Para filtrar os resultados de modo a incluir apenas registos da plataforma para tópicos de importação do Cloud Storage, use o campo filter. Segue-se um exemplo de um objeto de pedido JSON.

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

Veja e compreenda o formato do registo da plataforma

A secção seguinte inclui registos de plataformas de exemplo e descreve os campos dos registos de plataformas.

Todos os campos específicos do registo da plataforma estão contidos num objeto jsonPayload.

Cloud Storage

Falha do 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/my-project/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": "my-project",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}
Campo de registo Descrição
insertId Um identificador exclusivo da entrada do registo.
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 contentor do Cloud Storage que contém o objeto.
jsonPayload.cloudStorageFailure.objectName O nome do objeto do Cloud Storage.
jsonPayload.cloudStorageFailure.avroFailureReason Contém detalhes de erros de análise de Avro mais específicos. Este campo está vazio.
jsonPayload.topic O tópico Pub/Sub ao qual a mensagem se destinava.
jsonPayload.errorMessage Uma mensagem de erro legível.
resource.type O tipo de recurso. Sempre pubsub_topic.
resource.labels.project_id O Google Cloud ID do projeto.
resource.labels.topic_id O ID do tópico Pub/Sub.
timestamp Data/hora de geração da entrada do registo.
severity Nível de gravidade que é WARNING.
logName Nome do registo.
receiveTimestamp Data/hora de receção da entrada do registo.

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/my-project/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": "my-project"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}
Campo de registo Descrição
insertId Um identificador exclusivo da entrada do registo.
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 contentor 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 está vazio.
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 Google Cloud ID do projeto.
resource.labels.topic_id ID do tópico Pub/Sub.
timestamp Data/hora de geração da entrada do registo.
severity Nível de gravidade que é WARNING.
logName Nome do registo.
receiveTimestamp Hora em que a entrada de registo foi recebida pelo Cloud Logging.

Amazon MSK

Violação da API 

  {
  "insertId": "k3breb2q",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "awsMskFailure": {
      "apiViolationReason": {},
      "clusterArn": "arn:aws:kafka:us-east-1:291552718126:cluster/cluster-ingestion/abb9faea-4070-4eb76-9c21-f98abca92eaf-2",
      "kafkaTopic": "msk-topic",
      "partitionId": "1",
      "offset": "11"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/msk-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "msk-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T16:18:16.241643258Z"
}
Campo de registo Descrição
insertId Um identificador exclusivo da entrada do registo.
jsonPayload.@type Identifica o tipo de evento. Sempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.awsMskFailure.clusterArn O ARN do cluster do tópico a partir do qual os dados estão a ser carregados.
jsonPayload.awsMskFailure.kafkaTopic O nome do tópico do Kafka a partir do qual os dados estão a ser carregados.
jsonPayload.awsMskFailure.partitionId O ID da partição que contém a mensagem cuja ingestão falhou.
jsonPayload.awsMskFailure.offset O desvio na partição da mensagem cuja ingestão falhou.
jsonPayload.awsMskFailure.apiViolationReason Contém detalhes sobre a violação da API. Este campo está vazio.
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 Google Cloud ID do projeto.
resource.labels.topic_id ID do tópico Pub/Sub.
timestamp Data/hora de geração da entrada do registo.
severity Nível de gravidade que é WARNING.
logName Nome do registo.
receiveTimestamp Hora em que a entrada de registo foi recebida pelo Cloud Logging.

Azure Event Hubs

Violação da API 

{
  "insertId": "i1fbqnb12",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "azureEventHubsFailure": {
      "apiViolationReason": {},
      "namespace": "my-namespace",
      "eventHub": "my-event-hub",
      "partitionId": "1",
      "offset": "15"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/event-hubs-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "event-hubs-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T14:05:12.338211450Z"
}
Campo de registo Descrição
insertId Um identificador exclusivo da entrada do registo.
jsonPayload.@type Identifica o tipo de evento. Sempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.azureEventHubsFailure.namespace O espaço de nomes que contém o hub de eventos a partir do qual os dados estão a ser carregados.
jsonPayload.azureEventHubsFailure.eventHub O nome do hub de eventos a partir do qual os dados estão a ser carregados.
jsonPayload.azureEventHubsFailure.partitionId O ID da partição que contém a mensagem cuja ingestão falhou.
jsonPayload.azureEventHubsFailure.offset O desvio na partição da mensagem cuja ingestão falhou.
jsonPayload.azureEventHubsFailure.apiViolationReason Contém detalhes sobre a violação da API. Este campo está vazio.
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 Google Cloud ID do projeto.
resource.labels.topic_id ID do tópico Pub/Sub.
timestamp Data/hora de geração da entrada do registo.
severity Nível de gravidade que é WARNING.
logName Nome do registo.
receiveTimestamp Hora em que a entrada de registo foi recebida pelo Cloud Logging.

Confluent Cloud

Falha de texto 

{
  "insertId": "i1fbqnb14",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "confluentCloudFailure": {
      "apiViolationReason": {},
      "clusterId": "lma-1x18ae",
      "kafkaTopic": "confluent-topic",
      "partitionId": "1",
      "offset": "19"
    },
    "errorMessage": "The value of an attribute in the message exceeded the maximum allowed size of 1024 bytes. Number of bytes in the value: 1025. Key: my header. Value: my very large value …",
    "topic": "projects/my-project/topics/confluent-import-topic"
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "confluent-import-topic",
      "project_id": "my-project"
    }
  },
  "timestamp": "2025-02-03T16:18:14.693357960Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2025-02-03T17:03:11.428221440Z"
}
Campo de registo Descrição
insertId Um identificador exclusivo da entrada do registo.
jsonPayload.@type Identifica o tipo de evento. Sempre type.googleapis.com/google.pubsub.v1.IngestionFailureEvent.
jsonPayload.confluentCloudFailure.clusterId O ID do cluster que contém o tópico a ser carregado.
jsonPayload.confluentCloudFailure.kafkaTopic O nome do tópico do Kafka a partir do qual os dados estão a ser carregados.
jsonPayload.confluentCloudFailure.partitionId O ID da partição que contém a mensagem cuja ingestão falhou.
jsonPayload.confluentCloudFailure.offset O desvio na partição da mensagem cuja ingestão falhou.
jsonPayload.confluentCloudFailure.apiViolationReason Contém detalhes sobre a violação da API. Este campo está vazio.
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 Pub/Sub.
timestamp Data/hora de geração da entrada do registo.
severity Nível de gravidade que é WARNING.
logName Nome do registo.
receiveTimestamp Hora em que a entrada de registo foi recebida pelo Cloud Logging.
Apache Kafka® é uma marca comercial registada da The Apache Software Foundation ou das respetivas afiliadas nos Estados Unidos e/ou noutros países.