Usar registros da plataforma para resolver problemas de importação

Este guia explica como usar os logs da plataforma Google Cloud para resolver problemas ao usar tópicos de importação, incluindo os seguintes: tópicos de importação do 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.

Sobre os registros da plataforma

Um serviço Google Cloud com suporte gera seu 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.

Antes de começar

Verifique se você concluiu os pré-requisitos para criar o tópico que está usando:

Papéis e permissões necessárias

Antes de começar, verifique se você tem acesso ao Logging. Você precisa do papel (roles/logging.viewer) do Visualizador de registros do Identity and Access Management (IAM). 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:

Sobre falhas de ingestão de tópicos de importação

Os tópicos de importação podem encontrar problemas que impedem a ingestão 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 de dados. Por exemplo, ao usar um tópico de importação do Cloud Storage, você pode ter problemas ao 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 do Avro não poderão ter mais de 16 MB. Os blocos Avro 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. Se o valor for maior que o tamanho máximo, o par de chave-valor inteiro será descartado da mensagem quando ela for ingerida.

      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 transferência da mensagem.
  • Formato de dados

Importação de tópicos 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 de dados.

A lista a seguir descreve os motivos da falha de transferência em tópicos de importação 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.
  • 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. Se o valor for maior que o tamanho máximo, o par de chave-valor inteiro será descartado da mensagem quando ela for ingerida.

      Para mais informações sobre as diretrizes para usar chaves e atributos de mensagem, consulte Usar atributos para publicar uma mensagem.

Ativar registros da plataforma

Os registros da plataforma estão 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. Para desativar os registros da plataforma, atualize o tópico de importação.

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

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

Console

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

    Acesse Tópicos

  2. Selecione Criar tópico.

    A página de detalhes do tópico é aberta.

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

    Para mais informações sobre como nomear tópicos, consulte as diretrizes de nomenclatura.

  4. Selecione Adicionar uma assinatura padrão.

  5. Selecione Ativar ingestão.

  6. Mantenha as outras configurações padrão.
  7. Selecione 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 registros da plataforma, verifique se a flag --ingestion-log-severity está definida como WARNING ou um nível de gravidade mais baixo, como INFO ou DEBUG. Execute o comando gcloud pubsub topics create para o respectivo tópico que você está usando:

    Por exemplo, para ativar os registros da plataforma em um 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

Ativar registros da plataforma ao atualizar um tópico de importação

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

Console

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

    Acesse Tópicos

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

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

  4. Selecione Ativar registros 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 registros da plataforma, verifique se a gravidade do registro de transferência é WARNING ou um nível de gravidade mais baixo, como INFO ou DEBUG. Execute o comando gcloud pubsub topics update com todas as flags possíveis que especificam as configurações do respectivo tópico que você está usando:

    Por exemplo, para atualizar os registros em um tópico de importação do Cloud Storage, inclua a flag --ingestion-log-severity=WARNING no comando gcloud pubsub topics create e todos os valores de flag possíveis que especificam as configuraçõ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=WARNING

Desativar registros da plataforma

Para desativar os registros da plataforma para o respectivo tópico de importação que você está usando, faça o seguinte:

Console

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

    Acesse Tópicos

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

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

  4. Desmarque Ativar registros 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 registros da plataforma, verifique se a variável ingestion-log-severity está definida como DISABLED. Execute o comando gcloud pubsub topics update com todas as flags possíveis que especificam as configurações do respectivo tópico que você está usando:

    Por exemplo, para desativar os registros em um tópico de importação do Cloud Storage, inclua a flag --ingestion-log-severity=DISABLED no comando gcloud pubsub topics update e todas as flags possíveis que especificam as configuraçõ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=DISABLED

Conferir registros da plataforma

Para conferir os registros da plataforma do respectivo tópico de importação que você está usando, faça o seguinte:

Console do Google Cloud

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

    Acessar o Explorador de registros

  2. Selecione um projeto do Google Cloud.

  3. Se necessário, no menu Upgrade, alterne de Visualizador de registros legado para Explorador de registros.

  4. Clique no botão de alternância Mostrar consulta.

  5. Para filtrar seus registros e mostrar apenas as entradas dos respectivos tópicos de importação que você está usando (tópico de importação do Cloud Storage, do Azure Event Hubs, do Amazon MSK ou do Confluent Cloud), digite resource.type="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 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 dos respectivos tópicos de importação que você está usando, use o comando gcloud logging read.

Especifique um filtro para limitar os resultados aos registros da plataforma dos respectivos tópicos de importação que você está usando (tópico de importação do Cloud Storage, do Azure Event Hubs, do Amazon MSK ou do Confluent Cloud).

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.

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 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 Google Cloud .
resource.labels.topic_id O 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 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/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 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 projetoGoogle 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 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 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.awsMskFailure.clusterArn O ARN do cluster do tópico que está sendo ingerido.
jsonPayload.awsMskFailure.kafkaTopic O nome do tópico do Kafka de onde os dados estão sendo ingeridos.
jsonPayload.awsMskFailure.partitionId O ID da partição que contém a mensagem que não foi processada.
jsonPayload.awsMskFailure.offset O deslocamento na partição da mensagem que não foi processada.
jsonPayload.awsMskFailure.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 projetoGoogle 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 Cloud Logging.

Hubs de Eventos do Azure

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 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.azureEventHubsFailure.namespace O namespace que contém o hub de eventos de onde a ingestão é feita.
jsonPayload.azureEventHubsFailure.eventHub O nome do hub de eventos de onde os dados estão sendo transferidos.
jsonPayload.azureEventHubsFailure.partitionId O ID da partição que contém a mensagem que não foi processada.
jsonPayload.azureEventHubsFailure.offset O deslocamento na partição da mensagem que não foi processada.
jsonPayload.azureEventHubsFailure.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 projetoGoogle 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 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 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.confluentCloudFailure.clusterId O ID do cluster que contém o tópico que está sendo ingerido.
jsonPayload.confluentCloudFailure.kafkaTopic O nome do tópico do Kafka de onde os dados estão sendo ingeridos.
jsonPayload.confluentCloudFailure.partitionId O ID da partição que contém a mensagem que não foi processada.
jsonPayload.confluentCloudFailure.offset O deslocamento na partição da mensagem que não foi processada.
jsonPayload.confluentCloudFailure.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 Cloud Logging.
Apache Kafka® é uma marca registrada da The Apache Software Foundation ou afiliadas nos Estados Unidos e/ou em outros países.