Monitorar o status do job usando as notificações do Pub/Sub e o BigQuery

Neste documento, explicamos como monitorar as alterações no estado de jobs e tarefas configurando notificações do Pub/Sub. Você pode usar as notificações para vários casos de uso. Por exemplo, este documento explica como transmitir as notificações para uma tabela do BigQuery, que você pode usar para analisar os dados. Para saber mais sobre os casos de uso de notificações do Pub/Sub, consulte Escolher um tipo de assinatura na documentação do Pub/Sub.

Antes de começar

  • Se você nunca usou o Batch, consulte Primeiros passos com ele e ative-o concluindo os pré-requisitos para projetos e usuários.
  • Se você quiser configurar notificações do Pub/Sub para seus jobs em lote, faça o seguinte:

    1. Ative a API Pub/Sub.

      Ative a API

    2. Para receber as permissões necessárias para configurar um tópico e uma assinatura do Pub/Sub, peça ao administrador para conceder a você o papel de IAM Editor do Pub/Sub (roles/pubsub.editor) em um projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

      Também é possível receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

  • Os requisitos adicionais variam de acordo com o tipo de assinatura que você decidir configurar. Por exemplo, se você quiser transmitir e analisar notificações para uma tabela do BigQuery, faça o seguinte:

    1. Ative a API BigQuery.

      Ative a API

    2. Para garantir que a conta de serviço do Pub/Sub tenha as permissões necessárias para transmitir notificações do Pub/Sub para o BigQuery, peça ao administrador para conceder à conta de serviço do Pub/Sub o papel de IAM Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto do tópico do Pub/Sub.

      Para mais informações sobre como atribuir esse papel, acesse Atribuir papéis do BigQuery à conta de serviço do Pub/Sub.

    3. Verifique se todos os usuários que você quer analisar notificações no BigQuery têm as permissões necessárias.

      Para receber as permissões necessárias para consultar as notificações do Pub/Sub no BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM:

Configurar notificações do Pub/Sub para Batch

O Batch é compatível com notificações do Pub/Sub para alterações em estados de jobs e tarefas, que podem ser usadas para alertas, observabilidade ou análise.

Para configurar notificações do Pub/Sub para um ou mais jobs em lote, conclua as etapas descritas nas seções a seguir:

  1. Crie ou identifique um tópico do Pub/Sub para os jobs do Batch.
  2. Crie pelo menos uma assinatura para receber e usar as notificações do tópico.
  3. Configure jobs para enviar notificações ao tópico.

Depois de configurar as notificações do Pub/Sub para o Batch, é possível configurar cada job para enviar notificações específicas. É possível receber notificações sempre que os estados de jobs ou tarefas mudarem. Você também pode filtrar as notificações para estados específicos de jobs ou tarefas. O Pub/Sub não envia notificações para o primeiro estado em que um job ou uma tarefa entra. O Pub/Sub só envia notificações quando um job se move de um estado para outro. Para mais informações sobre os atributos que podem ser configurados para notificações do Pub/Sub, consulte Criar e executar um job que envia notificações de status do Pub/Sub.

Criar ou identificar um tópico do Pub/Sub para o Batch

Crie um novo tópico do Pub/Sub ou identifique um tópico atual do Pub/Sub que você quer usar para notificações em lote.

Conforme explicado posteriormente neste documento, os jobs não podem enviar notificações para esse tópico do Pub/Sub até que o administrador conceda permissões adicionais que permitam isso.

Crie uma assinatura para receber e usar as notificações

Para receber e usar mensagens publicadas em um tópico do Pub/Sub, você precisa criar pelo menos uma assinatura para esse tópico.

Por exemplo, uma opção é configurar seu tópico para transmitir as notificações dele para o BigQuery. Assim, ao executar jobs que publicam notificações, você poderá receber e analisar as notificações em uma tabela do BigQuery. Para mais informações, consulte Exemplo: receber e usar notificações do Pub/Sub no BigQuery neste documento.

Caso contrário, para saber mais sobre assinaturas e outras opções, consulte Visão geral de assinaturas na documentação do Pub/Sub.

Configurar jobs para enviar notificações ao tópico

Para configurar jobs que enviam notificações do Pub/Sub para seu tópico, siga as instruções na página Criar e executar um job que envia notificações de status do Pub/Sub. Especificamente, faça o seguinte:

  1. Se você ainda não fez isso, peça ao administrador para conceder todas as permissões necessárias para que os jobs enviem notificações ao seu tópico do Pub/Sub. Essas permissões estão listadas na seção Papéis obrigatórios dessa página.
  2. Criar e executar um job que ative as notificações do Pub/Sub definindo o campo notifications do job.

Exemplo: receber e usar notificações do Pub/Sub no BigQuery

Nas seções a seguir, explicamos um exemplo de caso de uso para receber e usar notificações do Pub/Sub no BigQuery. Ao configurar uma assinatura que transmite as notificações do Pub/Sub do tópico para uma tabela do BigQuery, é possível manter o histórico de alterações de estado de jobs e tarefas e consultar essas alterações.

Configurar uma assinatura que transmite notificações para o BigQuery

Configure uma assinatura do Pub/Sub que transmite notificações de um tópico para uma tabela do BigQuery fazendo o seguinte:

  1. Crie ou identifique um tópico do Pub/Sub para o Batch, caso ainda não tenha feito isso.

  2. Se você ainda não tiver um, crie um conjunto de dados do BigQuery.

  3. Crie uma tabela do BigQuery com a seguinte definição de esquema:

    [
  {
    "name": "data",
    "type": "STRING"
  },
  {
    "name": "subscription_name",
    "type": "STRING"
  },
  {
    "name": "message_id",
    "type": "STRING"
  },
  {
    "name": "attributes",
    "type": "JSON"
  },
  {
    "name": "publish_time",
    "type": "TIMESTAMP",
    "mode": "NULLABLE"
  }
]

  4. Crie uma assinatura do Pub/Sub que seja transmitida para o BigQuery e especifique as seguintes opções:

    • Tópico: selecione o tópico do Pub/Sub para o Batch.
    • Projeto: selecione o projeto que contém a tabela do BigQuery.
    • Conjunto de dados: selecione o conjunto de dados que contém a tabela do BigQuery.
    • Tabela: selecione a tabela que você criou na etapa anterior.
    • Selecione Usar esquema de tópicos.
    • Selecione Gravar metadados.

Agora, sempre que uma notificação do Pub/Sub for enviada para esse tópico, o Pub/Sub transmite essa notificação para a tabela do BigQuery. Depois de configurar jobs para enviar notificações do Pub/Sub, analise as notificações no BigQuery.

Analisar notificações no BigQuery

É possível analisar notificações no BigQuery depois de configurar uma assinatura em uma tabela do BigQuery para seu tópico e executar jobs que enviam notificações para esse tópico. Para analisar as notificações no BigQuery, execute uma consulta na coluna attributes da tabela do BigQuery. Os atributos que é possível consultar dependem de você ter configurado notificações para tarefas ou jobs.

É possível consultar os seguintes atributos das notificações de tarefas:

  • JobUID
  • NewTaskState
  • Region
  • TaskName
  • TaskUID
  • Type

É possível consultar os seguintes atributos das notificações de jobs:

  • JobUID
  • JobName
  • NewJobState
  • Region
  • Type

Por exemplo, a consulta a seguir mostra o JobUID associado a cada notificação:

select attributes.JobUID from `example-table`

A seguir