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, é possível usar o BEP para coletar informações para um plug-in de IDE ou um painel que mostra os resultados da build.
O protocolo é um conjunto de mensagens de buffer de protocolo com algumas semânticas definidas. 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 evento 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 do evento de build:dependendo do tipo de evento de build, ele pode ser uma string opaco 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 eventos de build no campo filhos. Por exemplo, o evento de build
PatternExpandedanuncia as metas que ele 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-filho. Todos os eventos de build, exceto o evento de build inicial, têm um ou mais eventos pai. Nem todos os eventos principais de um evento filho precisam ser publicados antes dele. Quando um build for concluído (com sucesso ou falha), 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 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 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 flags de linha de comando do Bazel a seguir 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 Build Event
Service
é um serviço gRPC genérico para publicar eventos de build. O protocolo do serviço de evento de build é independente do BEP e trata os eventos do BEP como bytes opacos.
O Bazel é enviado com uma implementação de cliente gRPC do protocolo do serviço de evento de build que
publica eventos do protocolo do 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.
Flags 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_lifecycle_events--bes_results_url--bes_timeout--bes_instance_name
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 flags 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 cache remoto. O Bazel vai fazer upload de todos os arquivos de saída para o cache remoto (incluindo 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.