Skip to content

Commit 9e7649f

Browse files
trunk-io[bot]trunk-io[bot]
authored
Merging 37db350 into trunk-temp/pr-956/1c63e17b-913e-4628-b92f-cfe56632f956
2 parents dcb63dc + 37db350 commit 9e7649f

File tree

2 files changed

+162
-0
lines changed

2 files changed

+162
-0
lines changed

‎bazel-bep/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,71 @@
33
Based on [crate](https://crates.io/crates/bazel-bep), [repo](https://github.com/ChristianBelloni/bazel-bep)
44

55
Original protos found [here](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto)
6+
7+
## Updating Protos for New Bazel Versions
8+
9+
### Current Situation
10+
11+
The upstream vendor crate (`bazel-bep`) has not been updated in over a year. As a result, we maintain our own copy of the proto definitions to ensure compatibility with newer Bazel versions. This is a short-term solution while we transition away from parsing JSON to using proto output directly from Bazel, which will help prevent breakage in the future.
12+
13+
### Why This Matters
14+
15+
When Bazel releases a new version, the Build Event Protocol (BEP) proto definitions may change. If our proto definitions are out of date, we may encounter:
16+
17+
- Parsing failures when processing BEP files from newer Bazel versions
18+
- Missing or incorrectly parsed fields
19+
- Compatibility issues that break our analytics pipeline
20+
21+
### How to Update Protos
22+
23+
When a new Bazel version is released, follow these steps to update the proto definitions:
24+
25+
1. **Identify the Bazel version and proto location**
26+
27+
- Check the [Bazel releases page](https://github.com/bazelbuild/bazel/releases) for the latest version
28+
- The proto files are located in the Bazel repository at:
29+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto`
30+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/action_cache.proto`
31+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/command_line.proto`
32+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/failure_details.proto`
33+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/package_load_metrics.proto`
34+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/publish_build_event.proto`
35+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_events.proto`
36+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/option_filters.proto`
37+
- `src/main/java/com/google/devtools/build/lib/buildeventstream/proto/invocation_policy.proto`
38+
39+
2. **Download the updated proto files**
40+
41+
- Clone or update the Bazel repository: `git clone https://github.com/bazelbuild/bazel.git`
42+
- Check out the specific Bazel version tag: `git checkout <version-tag>`
43+
- Copy the proto files from the Bazel repository to `bazel-bep/proto/`
44+
- Also copy any Google API proto files from `third_party/googleapis/google/api/` if they've changed
45+
46+
3. **Update dependencies if needed**
47+
48+
- Check if the proto changes require updates to `Cargo.toml` dependencies
49+
- Review any breaking changes in `prost`, `tonic-build`, or related crates
50+
51+
4. **Test the changes**
52+
53+
- Run `cargo build` to ensure the protos compile correctly
54+
- Run tests with BEP files from the new Bazel version
55+
- Verify that both JSON and binary BEP parsing still work correctly
56+
57+
5. **Document the Bazel version**
58+
- Update this README or add a comment indicating which Bazel version the protos are compatible with
59+
- Consider adding a test that verifies compatibility with specific Bazel versions
60+
61+
### Long-term Plan
62+
63+
The current approach of manually maintaining proto definitions is not scalable. We should:
64+
65+
1. **Move to proto output from Bazel**: Instead of parsing JSON, enforce using only Bazel's native proto output format to reduce compatibility issues
66+
2. **Automate proto updates**: Consider creating a script or CI job that automatically checks for Bazel updates and updates the proto files
67+
3. **Version compatibility testing**: Establish a testing strategy that verifies compatibility with multiple Bazel versions
68+
69+
### Related Files
70+
71+
- Proto definitions: `bazel-bep/proto/`
72+
- Build script: `bazel-bep/build.rs`
73+
- Parser implementations: `context/src/bazel_bep/parser.rs` (JSON) and `context/src/bazel_bep/binary_parser.rs` (binary)

‎context/src/bazel_bep/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Bazel Build Event Protocol (BEP) Parser
2+
3+
This module parses Bazel Build Event Protocol (BEP) files to extract test execution information for identifying test states. The BEP is a stream of events that Bazel emits during a build, providing detailed information about targets, test execution, and build artifacts.
4+
5+
## Overview
6+
7+
The BEP parser extracts information from two main event types:
8+
9+
- **TestResult events**: Individual test execution results
10+
- **TestSummary events**: Aggregated test execution summaries
11+
12+
The parser supports both JSON and binary proto formats, with automatic fallback from JSON to binary parsing if JSON parsing fails.
13+
14+
## Information Extracted from BEP
15+
16+
### 1. Target Information (Labels)
17+
18+
**Source**: `TestResult` and `TestSummary` event IDs
19+
20+
Each test target in Bazel has a unique label (e.g., `//trunk/hello_world/cc:hello_test`). The parser extracts these labels to:
21+
22+
- Group test results by target
23+
- Associate JUnit XML files with their corresponding targets
24+
- Track which targets were executed
25+
- Use for Codeowners associations
26+
27+
### 2. JUnit XML File Paths
28+
29+
**Source**: `TestResult.test_action_output` fields
30+
31+
The parser extracts paths to JUnit XML test result files. These paths can be:
32+
33+
- **Local file paths**: Absolute paths to XML files on the filesystem
34+
35+
- Example: `/tmp/hello_test/test.xml`
36+
- Example: `/tmp/hello_test/test_attempts/attempt_1.xml` (for retries)
37+
38+
- **Remote bytestream URIs**: References to files stored in remote caches
39+
- Example: `bytestream://build.example.io/blobs/1234/567`
40+
41+
**Multiple files per target**: A single target may produce multiple XML files in cases of:
42+
43+
- Test retries (each attempt generates its own XML)
44+
- Flaky test detection (multiple attempts with different outcomes)
45+
46+
**File filtering**: Only files with `.xml` extension are extracted from the `test_action_output` list.
47+
48+
### 3. Cache State
49+
50+
**Source**: `TestResult.execution_info` and `TestResult.cached_locally`
51+
52+
The parser determines whether a test result was cached:
53+
54+
- **`cached_locally`**: Test result was retrieved from local cache
55+
- **`cached_remotely`**: Test result was retrieved from remote cache (via `execution_info.cached_remotely`)
56+
57+
**Usage**:
58+
59+
- Cached test results are typically excluded from analytics (via `uncached_xml_files()` and `uncached_labels()`)
60+
- Cache state helps distinguish between actual test executions and cached results
61+
- XML file counts distinguish between total files and cached files
62+
63+
### 4. Test Status (Build Status)
64+
65+
**Latest status**: For tests with multiple attempts (retries), the parser tracks the status from the latest attempt.
66+
67+
### 5. Test Runner Report
68+
69+
**Source**: `TestSummary` events
70+
71+
The parser extracts aggregated test execution information from TestSummary events:
72+
73+
- **Overall status**: `overall_status` field (Passed, Failed, or Flaky)
74+
- **Start time**: `first_start_time` - when the first test attempt started
75+
- **End time**: `last_stop_time` - when the last test attempt completed
76+
- **Label**: The target label associated with the summary
77+
78+
**Usage**: Test runner reports provide high-level timing and status information that complements the detailed JUnit XML parsing. They are used for validation and to provide context when parsing JUnit files.
79+
80+
### 6. Attempt Numbers
81+
82+
**Source**: `TestResult` event ID (`TestResult.id.attempt`)
83+
84+
For tests that are retried (e.g., flaky tests), each attempt is tracked with an attempt number:
85+
86+
- Attempt numbers start at 1
87+
- Each retry increments the attempt number
88+
- Multiple XML files from the same target can have different attempt numbers
89+
90+
**Usage**:
91+
92+
- Attempt numbers are attached to individual test case runs to track which attempt they came from
93+
- Helps distinguish between different execution attempts of the same test
94+
- Used to merge results from multiple attempts into a single test result, especially when [`--flaky_test_attempts`](https://bazel.build/reference/command-line-reference#flag--flaky_test_attempts) results in an eventual success

0 commit comments

Comments
 (0)