El Protocolo de eventos de compilación (BEP) permite que programas de terceros obtengan estadísticas sobre una invocación de Bazel. Por ejemplo, puedes usar el BEP para recopilar información de 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 semántica definida sobre ellos. Incluye información sobre los resultados de compilaciones y pruebas, el progreso de las compilaciones, la configuración de compilaciones y mucho más. La BEP está diseñada para consumirse de manera programática y hacer que el análisis de los resultados de la línea de comandos de Bazel sea una tarea del pasado.
El protocolo de evento de compilación representa información sobre una compilación como eventos. Un evento de compilación es un mensaje de búfer de protocolo que consiste en 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 string opaca o una información estructurada que muestre más información sobre el evento de compilación. Un identificador de evento de compilación es único dentro de una compilación.
Children: Un evento de compilación puede anunciar otros eventos de compilación si incluye sus identificadores de evento de compilación en su campo secundario. Por ejemplo, el evento de compilación
PatternExpandedanuncia los destinos a los que se expande como secundarios. El protocolo garantiza que todos los eventos, excepto el primero, se anuncian 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 de ese evento. Ten en cuenta que la carga útil puede no ser el tipo esperado, pero podría ser un mensaje
Abortedsi la compilación se anuló de forma prematura.
Gráfico del evento de compilación
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 se deben publicar antes. Cuando se completa una compilación (correcta o con errores), todos los eventos anunciados se publican. En caso de una falla de Bazel o un error de transporte de red, es posible que nunca se publiquen algunos eventos de compilación anunciados.
La estructura del grafo de evento refleja el ciclo de vida de un comando. Cada grafo de BEP tiene la siguiente forma de 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 que produce el comando, como los archivos compilados y los resultados de pruebas, aparecen antes del evento
BuildFinished. - El evento
BuildFinishedpodría estar seguido por eventos que contengan información resumida sobre la compilación (por ejemplo, datos de métricas o de generación de perfiles).
Consumo del protocolo de eventos de compilación
Consumir en formato binario
Para consumir el BEP en un formato binario:
Haz que Bazel serializa los mensajes de búfer de protocolo en un archivo mediante la opción
--build_event_binary_file=/path/to/file. El archivo contendrá mensajes de búfer de protocolo serializados con cada mensaje delimitado por longitud. Cada mensaje tiene el prefijo de 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úfer de protocolo.Luego, escribe un programa que extraiga la información relevante del mensaje de búfer de protocolo serializado.
Consumir en formato JSON o de texto
Las siguientes marcas de línea de comandos de Bazel generarán la BEP en formatos legibles, como texto y JSON:
--build_event_text_file
--build_event_json_file
Crear servicio de eventos
El protocolo de servicio de eventos de compilación es un servicio genérico gRPC para publicar eventos de compilación. El protocolo de servicio de evento de compilación es independiente de la BEP y trata los eventos de BEP como bytes opacos.
Bazel incluye una implementación de cliente de gRPC del protocolo de servicios de eventos de compilación que
publica eventos de 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 la dirección con el esquema apropiado: grpc:// para gRPC de texto simple y grpcs:// para gRPC con TLS habilitado.
Marcas de servicios 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 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. Esta configuración se puede 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.
Compila servicios de eventos y almacenamiento en caché remoto
La BEP suele contener muchas referencias a los 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 tal como están en otras máquinas. Una forma de solucionar este problema es usar Bazel con el 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 la BEP), y el servidor de BES puede recuperar los archivos de la caché a los que se hace referencia.
Consulta el problema 3689 de GitHub para obtener más detalles.