El protocolo de eventos de compilación (BEP) permite que los programas de terceros obtengan estadísticas sobre una invocación de Bazel. Por ejemplo, puedes usar el BEP para recopilar información para un complemento de IDE o un panel que muestre los resultados de la compilación.
El protocolo es un conjunto de mensajes de búfer de protocolo con algunos semánticas definidos sobre él. Incluye información sobre los resultados de compilación y prueba, el progreso de la compilación, la configuración de la compilación y mucho más. El BEP se diseñó para consumirse de forma programática y hace que el análisis del resultado de la línea de comandos de Bazel sea cosa del pasado.
El Protocolo de eventos de compilación representa la información sobre una compilación como eventos. Un evento de compilación es un mensaje de búfer de protocolo que consta de un identificador de evento de compilación, un conjunto de identificadores de eventos secundarios y una carga útil.
Identificador de evento de compilación: Según el tipo de evento de compilación, puede ser una cadena opaca o información estructurada que revela más información sobre el evento de compilación. Un identificador de evento de compilación es único dentro de una compilación.
Elementos secundarios: Un evento de compilación puede anunciar otros eventos de compilación, ya que incluye sus identificadores de eventos de compilación en su campo de elementos secundarios. Por ejemplo, el evento de compilación
PatternExpandedanuncia los destinos a los que se expande como elementos secundarios. El protocolo garantiza que todos los eventos, excepto el primero, sean anunciados por un evento anterior.Carga útil: La carga útil contiene información estructurada sobre un evento de compilación, codificada como un mensaje de búfer de protocolo específico de ese evento. Ten en cuenta que la carga útil podría no ser del tipo esperado, sino un mensaje
Abortedsi la compilación se canceló antes de tiempo.
Cómo compilar un gráfico de eventos
Todos los eventos de compilación forman un grafo acíclico dirigido a través de su relación superior y secundaria. Cada evento de compilación, excepto el evento de compilación inicial, tiene uno o más eventos superiores. Ten en cuenta que no todos los eventos superiores de un evento secundario deben publicarse antes de este. Cuando se complete una compilación (se realice correctamente o con errores), se habrán publicado todos los eventos anunciados. En caso de que se produzca una falla de Bazel o un transporte de red fallido, es posible que algunos eventos de compilación anunciados nunca se publiquen.
La estructura del grafo de eventos refleja el ciclo de vida de un comando. Cada gráfico de BEP tiene la siguiente forma característica:
- El evento raíz siempre es un evento
BuildStarted. Todos los demás eventos son sus descendientes. - Los elementos secundarios inmediatos del evento BuildStarted contienen metadatos sobre el comando.
- Los eventos que contienen datos producidos por el comando, como los archivos compilados y los resultados de las pruebas, aparecen antes del evento
BuildFinished. - Es posible que después del evento
BuildFinishedse muestren eventos que contengan información de resumen sobre la compilación (por ejemplo, datos de métricas o perfiles).
Cómo consumir el Protocolo de eventos de compilación
Cómo consumir en formato binario
Para consumir el BEP en un formato binario, haz lo siguiente:
Haz que Bazel serialice los mensajes del búfer de protocolo en un archivo especificando la opción
--build_event_binary_file=/path/to/file. El archivo contendrá mensajes de búfer de protocolo serializados, cada uno de los cuales estará delimitado por la longitud. Cada mensaje tiene un prefijo con su longitud codificada como un número entero de longitud variable. Este formato se puede leer con el métodoparseDelimitedFrom(InputStream)de la biblioteca de búferes de protocolo.Luego, escribe un programa que extraiga la información relevante del mensaje del búfer de protocolo serializado.
Cómo consumir en formato de texto o JSON
Las siguientes marcas de línea de comandos de Bazel generarán el BEP en formatos legibles por humanos, como texto y JSON:
--build_event_text_file
--build_event_json_file
Servicio de evento de compilación
El protocolo del servicio de eventos de compilación es un servicio genérico de gRPC para publicar eventos de compilación. El protocolo del servicio de eventos de compilación es independiente del BEP y trata los eventos del BEP como bytes opacos.
Bazel se envía con una implementación de cliente de gRPC del protocolo de servicio de eventos de compilación que publica eventos del protocolo de eventos de compilación. Se puede especificar el extremo al que se enviarán los eventos con la marca --bes_backend=HOST:PORT. Si tu backend usa gRPC, debes anteponer a la dirección el esquema adecuado: grpc:// para gRPC de texto simple y grpcs:// para gRPC con TLS habilitado.
Marcas del servicio de evento de compilación
Bazel tiene varias marcas relacionadas con el protocolo del servicio de eventos de compilación, incluidas las siguientes:
--bes_backend--[no]bes_best_effort--[no]bes_lifecycle_events--bes_results_url--bes_timeout--project_id
Para obtener una descripción de cada una de estas marcas, consulta la referencia de la línea de comandos.
Autenticación y seguridad
La implementación del servicio de eventos de compilación de Bazel también admite la autenticación y TLS. Estos parámetros de configuración se pueden controlar con las siguientes marcas. Ten en cuenta que estas marcas también se usan para la ejecución remota de Bazel. Esto implica que el servicio de eventos de compilación y los extremos de ejecución remota deben compartir la misma infraestructura de autenticación y TLS.
--[no]google_default_credentials--google_credentials--google_auth_scopes--tls_certificate--[no]tls_enabled
Para obtener una descripción de cada una de estas marcas, consulta la referencia de la línea de comandos.
Servicio de evento de compilación y almacenamiento en caché remoto
Por lo general, el BEP contiene muchas referencias a archivos de registro (test.log, test.xml, etc. ) almacenados en la máquina en la que se ejecuta Bazel. Por lo general, un servidor BES remoto no puede acceder a estos archivos, ya que se encuentran en máquinas diferentes. Una forma de solucionar este problema es usar Bazel con caché remota. Bazel subirá todos los archivos de salida a la caché remota (incluidos los archivos a los que se hace referencia en el BEP) y, luego, el servidor de BES podrá recuperar los archivos a los que se hace referencia desde la caché.
Consulta el problema 3689 de GitHub para obtener más detalles.