End User Guide
BuildBarn Portal (or BBPortal, or bb-portal, etc. ) provides a storage mechanism, api, and graphical user interface for consuming and analyzing Build Event Protocol (BEP) data from local files or as streamed via the Build Event ServiceProtocol (BES). Depending on configuration it can be used to gain insights into your builds across the entire organization.
BBPortal has the concept of a build. Builds are no more than a grouping of invocations. You can group invocations into builds in any way you like. For example, a common use case is to group invocations by their associated pull request URL when run from CI. Invocation grouping is achieved by providing an environment variable (BUILD_URL). All invocations with a similar Build URL will share a common Build Id.
The /builds route provides a searchable table of builds, indexed by ID and Build URL. Just click on the search glass icon in the column header to search and narrow your results.
Tip
There are many options for searching, filtering and sorting table data throughout the application. Look for the helpful icons.
You can search for a specific build by Build ID or by Build URL. Mostly you’ll probably want to search by the build URL, which in many cases will be the Pull Request URL
You can view a build by clicking on the link in the /build view. This will show you a tabular list of all the associated invocations for the given build. You may navigate to any particular invocation by clicking on its invocation id.
To see more information about a particular invocation, click n the link to navigate to the /bazel-invocation details view.
Invocations contain details about the client invocation including metrics, targets, tests and source control information, etc. Invocations are the primary unit of interest in bbportal.
You can view a list of invocations at the /bazel-invocations endpoint. This view contains data about the user who launched the invocation (if provided), the Invocation ID. The Start Time of the invocation, as well as its duration, color coded status, and any associated Build information (if available).
The invocation ID is the same as the invocation ID surfaced by the bazel client.
User information will be automatically populated from the github action if available. You can also set this value via build metadata. For example you can add this to a bazelrc file somewhere:
build --build_metadata=user_ldap=demo-user
build --build_metadata=user_email=demo-user@example.com
You can search for an invocation by Invocation ID or Build ID in the bazel-invocations view. (look for those helpful search glass icons) You can also provide the invocation ID in the URL /bazel-invocations/{INVOCATION_ID} to navigate directly to a given invocation. Also you can access the invocation by clicking on (or copy/paste) the URL spawned by the bazel invocation in the command line.
Invocations contain a fair amount of detail about a given invocation and can be useful in troubleshooting build performance. Data for a given invocation is organized into tabs. Click a tab to view additional information about the invocation. BBPortal tries to remember which tab you last selected for a better user experience.
At the top of each invocation beneath the standard site navigation breadcrumbs, you will find the invocation details bar, which contains a quick summary of a few key elements of the invocation including;
-
The user if available
-
The invocation ID (click the button to copy this!)
-
The status of the invocation if available (color coded)
-
The Build ID if available (click to navigate to the build view)
-
The Duration of the invocation if available
-
The Profile button if available and if you've properly configured the frontend with a
NEXT_PUBLIC_BROWSER_URL
Note
The Profile Button is how you can access the build profile data.
You can use the profile button to download the raw profile data (typically a file named command.profile.gz). Clicking the button may prompt you to log in to buildbarn if authentication is conigured and if you’re not already authenticated.
Important
The profile button is only displayed if certain conditions are met. Namely, you've configured the frontend with a NEXT_PUBLIC_BROWSER_URL and the profile exists in your buildbarn cache
Once you’ve downloaded the profile data to your local machine, you can open a chrome tracing tab by typing chrome://tracing into the browser bar of a google chrome window.
Pressing enter will load the chrome tracing tool
You can load the profile by dragging and dropping the file onto the browser window or selecting the load button and navigating to the file you downloaded
For more information about using this tool, google search for chrome tracing tool and/or review this documentation from the chromium project, but you can navigate and really drill down into the memory profiler with this information.
This section contains more detailed information about the contents of each of the tabs on the invocations view
The default tab is the Overview tab.
This tab contains high level details about the invocation including:
-
The overall status of the build (color coded)
-
The invocation ID
-
The duration of the invocation
-
The user who triggered the invocation
-
the command used to launch the invocation
-
the CPU architecture of the system where the invocation was launched
-
the Configuration mnemonic for the same
-
The number of fetches performed as part of this invocation
The runner metrics tab contains information about runners and execution types. There is a graph that shows a breakdown of Action Runner execution types, as well as a sortable/filterable table with the runner type, the execution type, the count and the percentage or rate.
INFO: feel free to consult the build event stream code and documentation if you need more information about what a given metric represents or how its collected, why it might be empty or missing, etc.
The runner metrics tab can help you understand where different tasks were executed. (remotely, locally, etc)
The Action Cache Statistics tab contains details about hits and misses from the remote cache as provided by the build event service protocol
Summary Line
-
hit/miss bar graph
-
hits
-
misses
-
size in bytes
-
save time in ms
-
load time in ms
Misses are broken down further (where provided by the BES) and we provide a simple graph showing what caused misses for this invocation as well as a color coded, sortable table with Miss Reason, Count and Rate (%)
This tab can be useful in diagnosing cache hits and misses.
The actions Data tab contains a breakdown of actions provided by the BES. Namely there is a summary line containing the following data
-
Action Executed
-
Actions Created
-
Total User Time(ms)
-
Total System Time(ms)
As well as a broken down sortable table with per label data. Times are only provided by the BES if they can be accurately determined with a best effort approach so if some of these unexpected show a zero duration, this is because this information was not provided by the BES and there is no way for us to determine it otherwise.
There is also a graph breaking down user time, if these values are available for the given invocation in the BES payload.
Actions data can be useful in determining where your invocation is spending its time (compilation, mypy fetches, linking, etc.)
The artifacts tab contains a table with some high level details about types and sizes of artifacts seen in the cache for this invocation. In future, we may provide a way to download artifact outputs from the remote cache.
Artifacts metrics are useful in understanding the size and types of artifacts fetched from the cache
If available for a given invocation, we will display a memory metrics tab which includes a summary line
-
Peak Post GC Heap Size
-
Peak Post TC Tenured Space Heap Size
-
Used Heap Size Post Build
There is also a graph and table of garbage collection data, including the type and bytes of garbage collected.
Memory metrics can be helpful in spotting heap size regressions or garbage collection issues. Couple this with profiling data for a deep dive into invocation memory management
The timing metrics tab contains information about execution time.
-
Wall Time
-
Analysis
-
CPU Time
-
Execution
-
Actions Execution Start Time
If I’m completely honest, I don’t know how useful some of this information is on this tab, but we provided it for completeness since they went to the trouble of sending it.
If you optionally include the experimental flag to record network metrics, you’ll see another tab displayed. which contains the following
-
Bytes Received
-
Bytes Sent
-
Packets Received
-
Packets Sent
-
Peak Bytes Received (/s)
-
Peak Bytes Sent (/s)
-
Peak Packets Received (/s)
-
Peak Packets Sent (/s)
NOTE: This information can be included with the --experimental_collect_system_network_usage flag.
The targets tab is a sortable, filterable, navigable list of targets that provides information about target labels, durations, types, success, and abort reason (if any) for the given invocation. You can use this view to quickly navigate to information for a given target.
You can ask bbportal to optionally exclude saving target data to the database by setting the below environment variable to TRUE
BB_PORTAL_SKIP_SAVE_TARGETS
Alternatively, you can ask it to store even more data about targets with the variable set to TRUE
BB_PORTAL_ENRICH_TARGET_DATA
Clicking on a label will take you to a summary view for that target which includes trend over time data.
-
Targets Analyzed
-
Targets Built Successfuly
-
Targets Skipped
-
Targets Configured
-
Targets Configured not including aspects
The tests tab is also a sortable, filterable, navigable list of test targets that provides information about status, labels, strategy, cached locally or remotely (if determinable), and durations.
Clicking on a label will take you to a summary view for that test target which includes trend over time data.
The command line tab contains information about the explicit and effective command line and options for the bazel invocation and for bazel startup.
The source control tab contains information pulled from CI runs for the following. These values are automatically populated for github. In the future we will look at adding support for other source control systems.
-
Repository
-
Branch
-
Commit
-
Actor
-
Run ID for the github action
-
Pull Request
The problems tab contains debugging information for issues found by examining the BES. It is optionally displayed when there is an error with the build and it may or may not contain useful information. Consult the build logs for help diagnosing build errors.
When possible, we will provide a link that is ephemeral and shortlived to the build output in the buildbarn cache.
The /targets route contains data about unique individual targets across all invocations.
Click the search glass icon to type in a label and further refine your search result
The target details view contains additional data about a given target, including a graph of that targets run duration over time and a grid containing all invocations which included references to said target
Tests are a view of tests across the organization. It is similar to the targets view.
The Tests view provides a searchable list of test targets across all builds and invocations.
The test details view contains additional data about a given test target, including a graph of that targets run duration over time and a pass fail grid for recent runs of that test target
The bbportal application provides a graphql api endpoint as well as an API explorer.
The api endpoint is {your_bbportal_base_url}/graphql/api (so for example) https://bbportal.exampleco.io/graphql/api
The explorer is accessible at {your_bbportal_base_url}/graphiql (so for example) https://bbportal.exampleco.io/graphiql
This thing is handy if you want to build queries to pull metrics out of bbportal for your own dashboards or alerts. It also contains api documentation (expand the docs tab).