O Build Event Protocol (BEP) permite que programas de terceiros recebam 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. Ela inclui informações sobre os resultados da compilação e do teste, o progresso do build, a configuração do build e muito mais. O BEP destina-se a ser consumido de maneira programática 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 versão é uma mensagem de buffer de protocolo que consiste em um identificador de evento de versão, 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: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 do tipo esperado, mas pode ser uma mensagem
Abortedse o build for cancelado prematuramente.
Criar gráfico de eventos
Todos os eventos de build formam um gráfico acíclico dirigido pela relação pai e filho. Todo evento de build, exceto o de build inicial, tem um ou mais eventos pai. Nem todos os eventos pai de um evento filho precisam ser postados antes dele. Quando uma versão estiver concluída (bem-sucedida ou com falha), todos os eventos anunciados serão postados. No caso de uma falha do Bazel ou de um transporte de rede com falha, 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 a seguinte forma característica:
- O evento raiz é sempre
BuildStarted. Todos os outros eventos são descendentes. - Os filhos imediatos do evento BuildStarted contêm metadados sobre o comando.
- 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 consumir o protocolo de evento de build
Consumir em formato binário
Para consumir o BEP em um formato binário:
Faça com que o Bazel serialize as mensagens do 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 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 ao qual enviar os eventos usando a sinalização --bes_backend=HOST:PORT. Se o back-end usar gRPC, você precisará prefixar 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 evento de build, incluindo:
--bes_backend--[no]bes_best_effort--[no]bes_lifecycle_events--bes_results_url--bes_timeout--project_id
Para ver uma descrição de cada uma dessas sinalizações, consulte a Referência de linha de comando.
Autenticação e segurança
A implementação do serviço de evento de build do Bazel também oferece suporte à autenticação e ao TLS. Essas configurações podem ser controladas usando as sinalizações abaixo. Observe que essas sinalizações também são usadas para a execução remota do Bazel. Isso significa que o serviço de evento 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 ver uma descrição de cada uma dessas sinalizações, consulte a Referência de 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.