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

Neste documento, explicamos como monitorar mudanças no 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 de job.

Antes de começar

  1. Se você nunca usou o Batch, consulte Começar a usar o 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 em lote, faça o seguinte:

    1. Enable the Pub/Sub API.

      Enable the 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 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 por meio de papéis personalizados ou de outros papéis predefinidos.

  3. 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 em uma tabela do BigQuery, faça o seguinte:

    1. Enable the BigQuery API.

      Enable the 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 do IAM Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto do tópico do Pub/Sub.

      Para mais informações sobre como atribuir essa função, consulte Atribuir papéis do BigQuery à conta de serviço do Pub/Sub.

    3. Verifique se todos os usuários que você quer analisar as 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:

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

O lote 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 em um ou mais trabalhos em lote, siga as etapas descritas nas seções a seguir:

  1. Crie ou identifique um tópico do Pub/Sub para seus trabalhos em lote.
  2. Crie pelo menos uma assinatura para que o tópico receba e use 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. Você pode 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. 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.

Crie ou identifique 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 em lote.

Como explicado mais adiante neste documento, os jobs não podem enviar notificações para este tópico do Pub/Sub até que o administrador conceda outras permissões que permitam isso.

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

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

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, você pode 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.

Para saber mais sobre assinaturas e outras opções, 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 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 da 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 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 seu tópico para uma tabela do BigQuery, você pode manter o histórico de mudanças de estado de jobs e tarefas e fazer consultas a essas mudanças.

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

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

  1. Se 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 lote.
    • Projeto: selecione o projeto que contém sua 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 vai transmitir essa notificação para a tabela do BigQuery. Depois de configurar jobs para enviar notificações do Pub/Sub, é possível analisar 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 o 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 se você configurou 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 vagas:

  • 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