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 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 una semántica definida. Incluye información sobre los resultados de la compilación y la prueba, el progreso de la compilación, su configuración y mucho más. El BEP está diseñado para consumirse de manera programática, y hace que el análisis de los resultados de la línea de comandos de Bazel sea algo 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 una información estructurada que revele 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 los identificadores de eventos de compilación en su campo secundario. 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, se anuncien mediante 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 para ese evento. Ten en cuenta que es posible que la carga útil no sea del tipo esperado, pero podría ser un mensaje
Abortedsi la compilación se anuló de forma prematura.
Crea 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 principales de un evento secundario deben publicarse antes que él. Cuando se complete una compilación (de forma correcta o con errores), se publicarán todos los eventos anunciados. En caso de una falla de Bazel o una falla en el transporte de red, es posible que algunos eventos de compilación anunciados nunca se publiquen.
La estructura del gráfico 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 elementos subordinados. - Los elementos secundarios inmediatos del evento BuildStarted contienen metadatos sobre el comando.
- Los eventos que contienen datos que produce el comando, como los archivos compilados y los resultados de pruebas, aparecen antes del evento
BuildFinished. - Es posible que el evento
BuildFinishedvaya seguido de eventos que contengan información resumida sobre la compilación (por ejemplo, datos de métricas o de generación de perfiles).
Cómo consumir el protocolo de eventos de compilación
Consumir en formato binario
Para consumir el BEP en un formato binario, haz lo siguiente:
Haz que Bazel serializa 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 y cada mensaje 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 del búfer de protocolo.Luego, escribe un programa que extraiga la información relevante del mensaje del búfer de protocolo serializado.
Consumir en formatos 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 de servicio de eventos de compilación es un servicio genérico de gRPC para publicar eventos de compilación. El protocolo de servicio de eventos de compilación es independiente de BEP y trata los eventos de BEP como bytes opacos.
Bazel se envía con una implementación cliente de gRPC del protocolo del 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 agregar el prefijo a la dirección con el esquema adecuado: grpc:// para gRPC de texto simple y grpcs:// para gRPC con TLS habilitada.
Marcas del servicio de eventos 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 línea de comandos.
Autenticación y seguridad
La implementación del servicio de evento de compilación de Bazel también admite autenticación y TLS. Estos parámetros de configuración se pueden controlar con las siguientes funciones experimentales. 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 TLS y autenticación.
--[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 línea de comandos.
Servicio de eventos de compilación y almacenamiento en caché remoto
El BEP suele contener 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 remoto de BES no puede acceder a estos archivos porque se encuentran en diferentes máquinas. Una forma de solucionar este problema es usar Bazel con almacenamiento en caché remoto. Bazel subirá todos los archivos de salida a la caché remota (incluidos los archivos a los que se hace referencia en el BEP) y el servidor de BES puede recuperar los archivos a los que se hace referencia desde la caché.
Consulta el problema 3689 de GitHub para obtener más detalles.