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 build.
O protocolo é um conjunto de mensagens de buffer de protocolo com algumas semânticas definidas acima dele. Ela inclui informações sobre os resultados da compilação e dos testes, o progresso da compilação, a configuração da compilação e muito mais. O BEP precisa ser consumido de forma programática e faz com que a análise da saída da linha de comando do Bazel seja uma coisa do passado.
O Build Event Protocol representa informações sobre uma versão 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 evento filho e um payload.
Identificador de evento de build:dependendo do tipo de evento de build, 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 um build.
Filhos:um evento de build pode anunciar outros eventos de build, incluindo os identificadores de evento de build no campo filhos. Por exemplo, o evento de build
PatternExpandedanuncia os destinos em que 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 versão, codificada como uma mensagem de buffer de protocolo específica para esse evento. Observe que o payload pode não ser o tipo esperado, mas pode ser uma mensagem
Abortedse a versão for cancelada 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 inicial, têm um ou mais eventos pai. Nem todos os eventos pai de um evento filho precisam ser postados antes dele. Quando uma versão for concluída (bem-sucedida ou com falha), todos os eventos anunciados serão postados. Em 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 BEP tem a seguinte forma característica:
- O evento raiz é sempre um evento
BuildStarted. Todos os outros eventos são os descendentes dele. - 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, dados de métrica ou 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 conterá mensagens serializadas do buffer de protocolo, com cada mensagem sendo delimitada por comprimento. Cada mensagem é prefixada com seu comprimento codificado como um número inteiro de comprimento variável. Esse formato pode ser lido usando o métodoparseDelimitedFrom(InputStream)da biblioteca do buffer de protocolo.Em seguida, escreva um programa que extraia as informações relevantes da mensagem de buffer de protocolo serializada.
Consumir nos formatos de texto ou JSON
As seguintes sinalizações de linha de comando do Bazel vão gerar o BEP em formatos legíveis por humanos, como texto e JSON:
--build_event_text_file
--build_event_json_file
Serviço de evento de build
O protocolo Serviço
de evento de build
é um serviço gRPC genérico para publicar eventos de build. O protocolo do serviço de evento de versão é independente do BEP e trata os eventos do BEP como bytes opacos.
O Bazel é enviado com uma implementação de cliente gRPC do protocolo de serviço de evento de build que
publica eventos do Build Event Protocol. É possível especificar o endpoint para enviar os
eventos usando a sinalização --bes_backend=HOST:PORT. Se o back-end usar gRPC,
será necessário prefixar o endereço com o esquema apropriado: grpc:// para gRPC em texto simples
e grpcs:// para gRPC com TLS ativado.
Sinalizações do serviço de evento de build
O Bazel tem várias sinalizações 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--bes_instance_name
Para 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 eventos do build do Bazel também oferece suporte à autenticação e ao TLS. Essas configurações podem ser controladas usando as sinalizações abaixo. Essas sinalizações também são usadas para a execução remota do Bazel. Isso significa que o serviço de eventos de versão 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 sinalizações, consulte a Referência de linha de comando.
Serviço de eventos de build e armazenamento em cache remoto
O BEP normalmente contém muitas referências a arquivos de registros (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 contornar esse problema é usar o Bazel com armazenamento em cache remoto (link em inglês). O Bazel faz upload de todos os arquivos de saída para o cache remoto, incluindo os arquivos referenciados no BEP, e o servidor BES pode buscar os arquivos referenciados no cache.
Consulte o problema 3689 do GitHub (link em inglês) para saber mais.