O Build Event Protocol (BEP) permite que programas de terceiros tenham insights sobre uma invocação do Bazel. Por exemplo, é possível usar o BEP para coletar informações de um plug-in de IDE ou um painel que mostre os resultados da criação.
O protocolo é um conjunto de mensagens de buffer de protocolo com algumas semânticas definidas nele. Ele inclui informações sobre resultados de build e teste, progresso do build, configuração do build e muito mais. O BEP foi criado para ser consumido de forma programática e faz com que a análise da saída da linha de comando do Bazel fique no passado.
O protocolo de eventos 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 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 deles no campo "children". Por exemplo, o evento de build
PatternExpandedanuncia os destinos 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 o 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 por meio da relação entre pai e filho. Todos os eventos de build, exceto o inicial, têm um ou mais eventos principais. Nem todos os eventos principais de um evento secundário precisam ser postados antes dele. Quando um build for concluído (com ou sem êxito), todos os eventos anunciados terão sido postados. Em caso de falha do Bazel ou de um transporte de rede com falha, alguns eventos de build anunciados nunca serão postados.
A estrutura do gráfico de eventos reflete o ciclo de vida de um comando. Todo gráfico de BEP tem o seguinte formato característico:
- 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 testes, 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 de criação de perfil).
Consumir o Build Event Protocol
Consumir em 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 serializadas do buffer de protocolo, com cada mensagem delimitada por comprimento. Cada mensagem é prefixada com o comprimento dela 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 flags 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 Build Event
Service é um serviço gRPC genérico para publicar eventos de build. O protocolo Build Event
Service é independente do BEP e trata os eventos do BEP como bytes opacos.
O Bazel vem com uma implementação de cliente gRPC do protocolo Build Event Service que
publica eventos do protocolo Build Event. É possível especificar o endpoint para enviar os eventos usando a flag --bes_backend=HOST:PORT. Se o back-end usar gRPC, adicione o prefixo grpc:// ao endereço 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 Build Event Service do Bazel também é compatível com autenticação e 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
Normalmente, o BEP 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. Normalmente, um servidor BES remoto não consegue acessar esses arquivos porque eles estão em máquinas diferentes. Uma maneira de contornar esse problema é usar o Bazel com 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 mais detalhes.