O protocolo de evento de compilação (BEP, na sigla em inglês) 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 versão.
O protocolo é um conjunto de mensagens de buffer de protocolo com algumas semânticas definidas sobre ele. Ele inclui informações sobre resultados de build e teste, progresso do build, configuração do build e muito mais. O BEP é destinado a ser consumido programaticamente e torna a análise da saída da linha de comando do Bazel uma coisa do passado.
O protocolo do evento de versão representa informações sobre uma versão 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 evento filho e um payload.
Identificador de eventos 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 versão é exclusivo em uma versão.
Crianças: um evento de build pode anunciar outros eventos de build, incluindo os identificadores de evento de build no campo filho. Por exemplo, o evento de build
PatternExpandedanuncia os destinos que se expandem 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, codificada 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 o build for cancelado prematuramente.
Criar gráfico de eventos
Todos os eventos do build formam um gráfico acíclico dirigido pela relação pai e filho. Cada evento de versão, exceto o de criação inicial, tem um ou mais eventos pai. Observe que nem todos os eventos pai de um evento filho precisam ser postados antes dele. Quando uma versão é concluída (bem-sucedida ou falha), todos os eventos anunciados são publicados. No caso de uma falha do Bazel ou de um transporte de rede com falha, alguns eventos de versão anunciados podem nunca ser postados.
A estrutura do gráfico do evento reflete o ciclo de vida de um comando. Cada gráfico BEP tem o seguinte formato:
- 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, dados de métrica ou criação de perfil).
Como consumir o Build Event Protocol
Consumir em formato binário
Para consumir o BEP em formato binário:
Permita que o Bazel serialize as mensagens do buffer de protocolo para um arquivo especificando a opção
--build_event_binary_file=/path/to/file. O arquivo conterá mensagens de buffer de protocolo serializadas, cada uma sendo delimitada por comprimento. O comprimento de cada mensagem é prefixado como um número inteiro 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 produzirão a BEP em formatos legíveis, como texto e JSON:
--build_event_text_file
--build_event_json_file
Serviço de evento de versão
O protocolo do serviço de evento de build é um serviço gRPC genérico para publicar eventos de build. O protocolo de serviço de evento de build é independente da BEP e trata os eventos BEP como bytes opacos.
O Bazel é enviado com uma implementação do cliente gRPC do protocolo do serviço de evento de compilação que publica os eventos desse protocolo. É possível especificar o endpoint para enviar os eventos usando a sinalização --bes_backend=HOST:PORT. Se o back-end usar o gRPC,
você precisará 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 Build Service Service Protocol, 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 da linha de comando.
Autenticação e segurança
A implementação do serviço de evento de compilação do Bazel também é compatível com autenticação e 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 implica que o serviço de evento 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 ver uma descrição de cada uma dessas sinalizações, 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 é executado. Um servidor BES remoto geralmente não pode acessar esses arquivos como estão em máquinas diferentes. Uma maneira de contornar esse problema é usar o Bazel com armazenamento em cache remoto. O Bazel fará 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 ver mais detalhes.