Protocolo del evento de compilación

Informar un problema Ver fuente

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 de un complemento de IDE o un panel que muestre resultados de compilación.

El protocolo es un conjunto de mensajes de búfer de protocolo con cierta semántica definida sobre él. Incluye información sobre la compilación y los resultados de las pruebas, el progreso de la compilación, la configuración de la compilación y mucho más. Se espera que el BEP se consuma de manera programática y que el análisis del resultado de la línea de comandos de Bazel sea algo del pasado.

El protocolo de eventos 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 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, podría ser una string opaca o una información estructurada que revele más 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 incluyendo sus identificadores de eventos de compilación en su campo secundario. Por ejemplo, el evento de compilación PatternExpanded anuncia los destinos a los que se expande como elementos secundarios. El protocolo garantiza que un evento anterior anuncie todos los eventos, excepto el primero.

  • Carga útil: La carga útil contiene información estructurada sobre un evento de compilación, codificada como un mensaje del 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 Aborted si la compilación se anuló antes de tiempo.

Gráfico de eventos de compilación

Todos los eventos de compilación forman un grafo acíclico dirigido a través de su relación de elemento superior y secundario. Todos los eventos de compilación, excepto el inicial, tienen uno o más eventos superiores. Ten en cuenta que no todos los eventos superiores de un evento secundario necesariamente deben publicarse antes. Cuando se completa una compilación (se realiza de manera correcta o falla), se publican todos los eventos anunciados. En caso de una falla de Bazel o un error 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 de características:

  1. El evento raíz siempre es un evento BuildStarted. Todos los demás eventos son sus elementos subordinados.
  2. Los elementos secundarios inmediatos del evento BuildStarted contienen metadatos sobre el comando.
  3. Los eventos que contienen datos que genera el comando, como los archivos compilados y los resultados de las pruebas, aparecen antes del evento BuildFinished.
  4. Al evento BuildFinished puede estar seguido de eventos que contienen 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

Consumo en formato binario

Para consumir el BEP en un formato binario, haz lo siguiente:

  1. Haz que Bazel serialice los mensajes del búfer de protocolo en un archivo mediante la especificación de la opción --build_event_binary_file=/path/to/file. El archivo contendrá mensajes del búfer de protocolo serializado, y cada mensaje se delimitará por 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étodo parseDelimitedFrom(InputStream) de la biblioteca de búfer de protocolo.

  2. Luego, escribe un programa que extraiga la información relevante del mensaje del búfer de protocolo serializado.

Consumo en formato de texto o JSON

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

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 evento de compilación es independiente de BEP y trata los eventos de 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. Puedes 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 habilitado.

Marcas del servicio de evento de compilación

Bazel tiene varias marcas relacionadas con el protocolo de servicio de eventos de compilación, incluidas las siguientes:

  • --bes_backend
  • --[no]bes_best_effort
  • --[no]bes_lifecycle_events
  • --bes_results_url
  • --bes_timeout
  • --bes_instance_name

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 eventos de compilación de Bazel también admite la autenticación y TLS. Esta configuración se puede controlar con las marcas que se indican a continuación. 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 línea de comandos.

Servicio de eventos de compilación y almacenamiento en caché remoto

Por lo general, la 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 de 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 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 podrá recuperar los archivos a los que se hace referencia de la caché.

Consulta el problema 3689 de GitHub para obtener más detalles.