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

Neste documento, explicamos como monitorar mudanças de estado de jobs e tarefas configurando notificações do Pub/Sub. É possível 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 pode ser usada para analisar os dados. Para saber mais sobre os casos de uso das notificações do Pub/Sub, consulte Escolher um tipo de assinatura na documentação do Pub/Sub.

Como alternativa, se você quiser exportar todas as informações sobre um job para o BigQuery, consulte Exportar informações do job em vez disso.

Observação: o Pub/Sub e o BigQuery são produtos separados Google Cloud que têm preços diferentes. Para mais informações, consulte Preços do Pub/Sub e Preços do BigQuery.

Antes de começar

1. Se você nunca usou o Batch, consulte Introdução ao Batch e ative o Batch concluindo os pré-requisitos para projetos e usuários.
2. Se você quiser configurar notificações do Pub/Sub para seus jobs do Batch, faça o seguinte:

   1. Ative a API Pub/Sub.

      Funções necessárias para ativar APIs

      Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

      Ativar 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ê opapel do IAM de editor do Pub/Sub (roles/pubsub.editor) em um projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

   Observação: depois de configurar um tópico e uma assinatura do Pub/Sub, o administrador precisará conceder permissões adicionais a vários principais para permitir que os jobs enviem notificações para esse tópico. Especificamente, os papéis necessários estão listados na página Criar e executar um job que envia notificações de status do Pub/Sub.
3. Outros requisitos variam de acordo com o tipo de assinatura que você decide 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.

      Funções necessárias para ativar APIs

      Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de proprietário (roles/owner). Caso contrário, você pode receber essa permissão com o papel de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

      Ativar 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 o papel do IAM de editor de dados do BigQuery (roles/bigquery.dataEditor) à conta de serviço do Pub/Sub no projeto do tópico do Pub/Sub.

      Importante: conceda esse papel à conta de serviço do Pub/Sub, não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.

      Para mais informações sobre como atribuir esse papel, consulte 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 notificações do Pub/Sub no BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM:

      • Usuário de jobs do BigQuery (roles/bigquery.jobUser) no projeto da tabela do BigQuery
      • Leitor de dados do BigQuery (roles/bigquery.dataViewer) na tabela do BigQuery

Configurar notificações do Pub/Sub para o Batch

O Batch oferece suporte a notificações do Pub/Sub para mudanças nos 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 do Batch, conclua as etapas descritas nas seções a seguir:

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

Depois de configurar as notificações do Pub/Sub para o Batch, você pode configurar cada job para enviar notificações específicas. É possível receber notificações sempre que os estados de jobs ou tarefas mudarem ou 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 tarefa entra. Ele só envia notificações quando um job passa de um estado para outro.

Importante: Devido a um problema conhecido, o Pub/Sub pode não enviar notificações para todos os estados intermediários quando um job ou tarefa muda muito rapidamente. É possível atenuar esse problema visualizando o histórico de estados por eventos de status. Para mais informações, consulte O Pub/Sub pode não enviar notificações para estados intermediários durante mudanças rápidas.

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 do Pub/Sub que você quer usar para notificações do Batch.

Conforme explicado mais adiante 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.

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

Para receber e usar mensagens publicadas em um tópico do Pub/Sub, é necessário criar pelo menos uma assinatura para esse tópico.

Por exemplo, uma opção é configurar o tópico para transmitir as notificações para o BigQuery. Em seguida, ao executar jobs que publicam notificações, é possível 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 de assinatura, consulte Visão geral das assinaturas na documentação do Pub/Sub.

Configurar jobs para enviar notificações ao seu 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 tiver feito 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 necessários dessa página.
2. Crie e execute 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

As seções a seguir explicam um caso de uso de exemplo 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 mudanças de estado de jobs e tarefas e consultar essas mudanças.

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. Se você ainda não tiver feito isso, crie ou identifique um tópico do Pub/Sub para o Batch.

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 transmita 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 sua tabela do BigQuery.
   • Conjunto de dados: selecione o conjunto de dados que contém sua 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 transmitirá essa notificação para a tabela do BigQuery. Depois de configurar jobs para enviar notificações do Pub/Sub, é possível analisar as notificações no BigQuery.

Analisar notificações no BigQuery

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

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

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

É possível consultar os seguintes atributos de 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

• Saiba como criar e executar um job que envia notificações de status do Pub/Sub.
• Saiba mais sobre as assinaturas do Pub/Sub.
• Saiba mais sobre o BigQuery Analytics.