O Build Event Protocol (BEP, na sigla em inglês) permite que programas de terceiros tenham insights sobre uma invocação do Bazel. Por exemplo, você pode usar o BEP para coletar informações de um plug-in de IDE ou um painel que mostre os resultados da build.
O protocolo é um conjunto de protocol buffer mensagens com algumas semânticas definidas nele. Ele inclui informações sobre resultados de build e teste, progresso da build, configuração da build e muito mais. O BEP foi criado para ser consumido de forma programática e torna a análise da saída da linha de comando do Bazel algo do passado.
O Build Event Protocol representa informações sobre uma 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 build: dependendo do tipo de evento de build, ele pode ser uma string opaca ou informações estruturadas que revelam mais sobre o evento de build. Um identificador de evento de build é exclusivo em uma build.
Filhos: um evento de build pode anunciar outros eventos de build, incluindo os identificadores de eventos de build no campo filhos. 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 evento, sejam anunciados por um evento anterior.Payload: O 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 o tipo esperado, mas pode ser uma mensagem
Abortedse a build for interrompida prematuramente.
Gráfico de eventos de build
Todos os eventos de build formam um gráfico acíclico dirigido pela relação pai-filho. Todos os eventos de build, exceto o inicial, têm um ou mais eventos pai. Nem todos os eventos pai de um evento filho precisam necessariamente ser postados antes dele. Quando uma build é concluída (com êxito ou falha) todos os eventos anunciados são postados. Em caso de falha do Bazel ou de transporte de rede, alguns eventos de build anunciados podem nunca ser postados.
A estrutura do gráfico de eventos reflete o ciclo de vida de um comando. Cada gráfico do BEP tem o seguinte formato característico:
- O evento raiz é sempre um
BuildStartedevento. 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 testes, aparecem antes do
BuildFinishedevento. - O
BuildFinishedevento pode ser seguido por eventos que contêm informações de resumo sobre a build (por exemplo, dados de métricas ou de criação de perfil).
Como consumir o Build Event Protocol
Consumir no formato binário
Para consumir o BEP em um formato binário:
Faça com que o Bazel serializa 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 de buffer de protocolo serializadas, com cada mensagem sendo 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étodo da biblioteca de buffer de protocolo.parseDelimitedFrom(InputStream)Em seguida, escreva um programa que extraia as informações relevantes da mensagem de buffer de protocolo serializada.
Consumir em formatos de texto ou JSON
As seguintes flags 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 Build Event
Service
Protocol é um serviço gRPC genérico para publicar eventos de build. O protocolo do Build Event
Service é independente do BEP e trata os eventos do BEP como bytes opacos.
O Bazel é fornecido com uma implementação de cliente gRPC do protocolo do Build Event Service que
publica eventos do Build Event Protocol. É possível especificar o endpoint para enviar os
eventos usando a --bes_backend=HOST:PORT flag. 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.
Flags do Build Event Service
O Bazel tem várias flags relacionadas ao protocolo do Build Event Service, 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 Build Event Service do Bazel também oferece suporte à autenticação e ao TLS. Essas configurações podem ser controladas usando as flags abaixo. Essas flags também são usadas para a execução remota do Bazel. Isso implica que o Build Event Service 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.
Build Event Service e armazenamento em cache remoto
O BEP normalmente contém muitas referências a arquivos de registro (test.log, test.xml, etc. ) armazenados na máquina em que o Bazel está em execução. Um servidor BES remoto normalmente não pode acessar esses arquivos, porque eles estão em máquinas diferentes. Uma maneira de contornar esse problema é usar o Bazel com armazenamento em cache remoto. O Bazel vai fazer o upload de todos os arquivos de saída para o cache remoto (incluindo os arquivos referenciados no BEP), e o servidor BES poderá buscar os arquivos referenciados no cache.
Consulte o problema 3689 do GitHub (link em inglês) para mais detalhes.