O Build Event Protocol (BEP) permite que programas de terceiros tenham insights sobre uma invocação do Bazel. Por exemplo, você pode usar o BEP para coletar informações para um plug-in de ambiente de desenvolvimento integrado ou um painel que exibe resultados de compilação.
O protocolo é um conjunto de mensagens de buffer de protocolo com algumas semânticas definidas nele. Ele inclui informações sobre resultados de build e teste, progresso do build, configuração do build e muito mais. O BEP tem como objetivo ser consumido programaticamente e torna a análise da saída da linha de comando do Bazel uma coisa do passado.
O protocolo de eventos de build representa informações sobre um build como eventos. Um evento de build é uma mensagem de buffer de protocolo que consiste em um identificador de evento de build, um conjunto de identificadores de eventos filhos e um payload.
Identificador de evento de versão:dependendo do tipo de evento de versão, pode ser uma string opaca ou informações estruturadas que revelem mais sobre o evento. Um identificador de evento de versão é exclusivo dentro de uma versão.
Filhos:um evento de build pode anunciar outros eventos de build, incluindo os identificadores dele no campo filho. Por exemplo, o evento de build
PatternExpandedanuncia os destinos para os quais ele se expande como filhos. O protocolo garante que todos os eventos, exceto o primeiro, sejam anunciados por um evento anterior.Payload: contém informações estruturadas sobre um evento de build, codificadas como uma mensagem de buffer de protocolo específica para esse evento. O payload pode não ser do tipo esperado, mas pode ser uma mensagem
Abortedse o build for interrompido prematuramente.
Criar gráfico de eventos
Todos os eventos de build formam um gráfico acíclico dirigido pela relação pai e filho. Todos os eventos de build, exceto o evento de build inicial, têm um ou mais eventos pai. Nem todos os eventos pai de um evento filho precisam ser postados antes dele. Quando uma build for concluída (com sucesso ou sem sucesso), todos os eventos anunciados serão publicados. Em caso de falha do Bazel ou de um transporte de rede com falha, alguns eventos de build anunciados podem nunca ser publicados.
A estrutura do gráfico de eventos reflete o ciclo de vida de um comando. Cada gráfico do BEP tem a seguinte forma característica:
- O evento raiz é sempre um evento
BuildStarted. Todos os outros eventos são descendentes dele. - Os filhos imediatos do evento BuildStarted contêm metadados sobre o comando.
- Os eventos que contêm dados produzidos pelo comando, como arquivos criados e resultados
de teste, aparecem antes do evento
BuildFinished. - O evento
BuildFinishedpode ser seguido por eventos que contêm informações resumidas sobre o build (por exemplo, métricas ou dados de criação de perfil).
Como usar o Build Event Protocol
Consumir em formato binário
Para consumir o BEP em um formato binário:
Faça com que o Bazel serialize as mensagens de buffer de protocolo em um arquivo especificando a opção
--build_event_binary_file=/path/to/file. O arquivo vai conter mensagens serializadas do buffer de protocolo, com cada mensagem delimitada por comprimento. Cada mensagem é prefixada com o comprimento codificado como um número inteiro de comprimento variável. Esse formato pode ser lido usando o métodoparseDelimitedFrom(InputStream)da biblioteca de buffer de protocolo.Em seguida, escreva um programa que extraia as informações relevantes da mensagem serializada do buffer de protocolo.
Consumir em formatos de texto ou JSON
As seguintes sinalizações de linha de comando do Bazel vão gerar o BEP em formatos legíveis, como texto e JSON:
--build_event_text_file
--build_event_json_file
Serviço de evento de build
O protocolo de serviço de evento de criação é um serviço gRPC genérico para publicar eventos de build. Esse protocolo é independente do BEP e trata esses eventos como bytes opacos.
O Bazel acompanha uma implementação de cliente gRPC do protocolo do serviço de evento de build que
publica eventos do protocolo de evento de build. É possível especificar o endpoint para enviar os
eventos usando a flag --bes_backend=HOST:PORT. Se o back-end usar o gRPC,
prefixe o endereço com o esquema apropriado: grpc:// para gRPC de texto simples
e grpcs:// para gRPC com TLS ativado.
Sinalizações do serviço de evento de build
O Bazel tem várias flags relacionadas ao protocolo do serviço de eventos de build, incluindo:
--bes_backend--[no]bes_best_effort--[no]bes_lifecycle_events--bes_results_url--bes_timeout--project_id
Para uma descrição de cada uma dessas flags, consulte a referência da linha de comando.
Autenticação e segurança
A implementação do serviço de eventos de build do Bazel também oferece suporte à autenticação e ao TLS. Essas configurações podem ser controladas usando as sinalizações abaixo. Essas flags também são usadas para a execução remota do Bazel. Isso implica que o serviço de eventos de build e os endpoints de execução remota precisam compartilhar a mesma infraestrutura de autenticação e TLS.
--[no]google_default_credentials--google_credentials--google_auth_scopes--tls_certificate--[no]tls_enabled
Para uma descrição de cada uma dessas flags, consulte a referência da linha de comando.
Serviço de evento de build e armazenamento em cache remoto
O BEP geralmente contém muitas referências a arquivos de registro (test.log, test.xml etc.) armazenados na máquina em que o Bazel está sendo executado. Um servidor BES remoto normalmente não pode acessar esses arquivos, porque eles estão em máquinas diferentes. Uma maneira de resolver esse problema é usar o Bazel com armazenamento em cache remoto. O Bazel faz upload de todos os arquivos de saída para o cache remoto (incluindo arquivos referenciados no BEP) e o servidor BES pode buscar os arquivos referenciados do cache.
Consulte o problema 3689 do GitHub (link em inglês) para saber mais.