go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/bisection/proto/v1/analyses.proto

// Copyright 2023 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package luci.bisection.v1;

import "google/api/field_behavior.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "go.chromium.org/luci/bisection/proto/v1/bugs.proto";
import "go.chromium.org/luci/bisection/proto/v1/common.proto";
import "go.chromium.org/luci/bisection/proto/v1/culprits.proto";
import "go.chromium.org/luci/bisection/proto/v1/heuristic.proto";
import "go.chromium.org/luci/bisection/proto/v1/nthsection.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/buildbucket/proto/builder_common.proto";

option go_package = "go.chromium.org/luci/bisection/proto/v1;bisectionpb";

// Analyses service includes all methods related to failure analyses
// called from LUCI Bisection clients, such as SoM.
service Analyses {
  // GetAnalysis is used to get an analysis by analysis ID.
  rpc GetAnalysis(GetAnalysisRequest) returns (Analysis);

  // QueryAnalysis is used to query for the status and result of analyses.
  // The user can pass in the failure information to retrieve the analyses.
  rpc QueryAnalysis(QueryAnalysisRequest) returns (QueryAnalysisResponse);

  // ListAnalyses is used to get existing analyses.
  // Most recently created analyses are returned first.
  rpc ListAnalyses(ListAnalysesRequest) returns (ListAnalysesResponse);

  // TriggerAnalysis is used to trigger an analysis for a failed build.
  // This RPC is called from a LUCI Bisection client like SoM or Milo.
  // If an existing analysis is found for the same failure, no new analysis
  // will be triggered.
  rpc TriggerAnalysis(TriggerAnalysisRequest) returns (TriggerAnalysisResponse);

  // Update the information of an analysis,
  // e.g. update the bugs associated with an analysis.
  // Mainly used by SoM, since LUCI Bisection does not have any information
  // about bugs created by sheriffs.
  rpc UpdateAnalysis(UpdateAnalysisRequest) returns (Analysis);

  // ListTestAnalyses is used to get existing test analyses.
  // Most recently created test analyses are returned first.
  rpc ListTestAnalyses(ListTestAnalysesRequest) returns (ListTestAnalysesResponse);

  // GetTestAnalysis is used to get a test analysis by its ID.
  rpc GetTestAnalysis(GetTestAnalysisRequest) returns (TestAnalysis);

  // BatchGetTestAnalyses is an RPC to batch get test analyses for test failures.
  // At this moment it only support getting the bisection for the ongoing test failure.
  // TODO(@beining): This endpoint can be extended to support returning bisection for
  // any test failure by specifying source position in the request.
  rpc BatchGetTestAnalyses(BatchGetTestAnalysesRequest) returns (BatchGetTestAnalysesResponse);

}

message GetAnalysisRequest {
  // ID of the analysis.
  int64 analysis_id = 1 [ (google.api.field_behavior) = REQUIRED ];
}

message QueryAnalysisRequest {
  // The build failure information to query for the analyses.
  BuildFailure build_failure = 1;
}

message QueryAnalysisResponse {
  // The analyses corresponding to the QueryAnalysisRequest.
  repeated Analysis analyses = 1;
}

message ListAnalysesRequest {
  // Optional. The maximum number of analyses to be returned in the response.
  // The service may return fewer than this value.
  // If unspecified, at most 50 analyses will be returned.
  // The maximum value is 200; values above 200 will be coerced to 200.
  int32 page_size = 1;
  // Optional. A page token, received from a previous `ListAnalyses` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListAnalyses` must
  // match the call that provided the page token,
  // with the exception of page_size and page_token.
  string page_token = 2;
}

message ListAnalysesResponse {
  // The analyses corresponding to the ListAnalysesRequest.
  repeated Analysis analyses = 1;
  // The token to send as `page_token` to retrieve the next page of analyses.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

message TriggerAnalysisRequest {
  // Failure for which to trigger the analysis.
  BuildFailure build_failure = 1;
  // Optionally, the client can pass the bug associated with the failure.
  // LUCI Bisection will update the bug with analysis progress/result.
  // This is mainly for SoM, which has information about bugs associated
  // with a failure.
  repeated BugInfo bug_info = 2;
}

message TriggerAnalysisResponse {
  // The analysis result corresponding to the request.
  // It is either a new analysis or an existing one.
  Analysis result = 1;
  // is_new_analysis will be set to true if a new analysis is triggered.
  // It will be set to false if an existing analysis is used instead.
  bool is_new_analysis = 2;
}

// Update the information of an analysis,
// e.g. update the bugs associated with an analysis.
// LUCI Bisection will comment on the bug with analysis progress/results.
// Note: Existing bugs associated with the analysis will be replaced.
message UpdateAnalysisRequest {
  // ID of the analysis.
  string analysis_id = 1 [ (google.api.field_behavior) = REQUIRED ];
  repeated luci.bisection.v1.BugInfo bug_info = 2;
}

// AnalysisRunStatus focusses on whether the analysis is currently running, not
// the actual result of the analysis.
enum AnalysisRunStatus {
  ANALYSIS_RUN_STATUS_UNSPECIFIED = 0;
  // The analysis started and is still running.
  STARTED = 2;
  // The analysis has ended (either it stopped naturally or ran into an error).
  ENDED = 3;
  // The analysis has been canceled.
  CANCELED = 4;
}

// Analysis contains result of an analysis.
// Next available tag: 15.
message Analysis {
  // ID to identify this analysis.
  int64 analysis_id = 1;
  // The failure associated with the analysis.
  BuildFailure build_failure = 2;
  // Result status of the analysis.
  luci.bisection.v1.AnalysisStatus status = 3;
  // Run status of the analysis.
  // See https://go.chromium.org/luci/bisection/proto/v1/#AnalysisRunStatus
  AnalysisRunStatus run_status = 4;
  // Buildbucket ID for the last passed build.
  int64 last_passed_bbid = 5;
  // Buildbucket ID for the first failed build.
  int64 first_failed_bbid = 6;
  // Timestamp for the created time of the analysis.
  google.protobuf.Timestamp created_time = 7;
  // Timestamp for the last updated time of the analysis.
  google.protobuf.Timestamp last_updated_time = 8;
  // Timestamp for the end time of the analysis.
  google.protobuf.Timestamp end_time = 9;
  // Result of heuristic analysis.
  luci.bisection.v1.HeuristicAnalysisResult heuristic_result = 10;
  // Result of nth-section analysis.
  luci.bisection.v1.NthSectionAnalysisResult nth_section_result = 11;
  // Builder for the first failed build.
  buildbucket.v2.BuilderID builder = 12;
  // Type of the failure associated with the analysis.
  BuildFailureType build_failure_type = 13;
  // The culprits for the analysis.
  // For some rare cases, we may get more than one culprit for a regression
  // range. So we set it as repeated field.
  repeated luci.bisection.v1.Culprit culprits = 14;
}

enum BuildFailureType {
  BUILD_FAILURE_TYPE_UNSPECIFIED = 0;
  COMPILE = 1;
  TEST = 2;
  INFRA = 3;
  OTHER = 4;
}

message BuildFailure {
  // Buildbucket ID for the failed build.
  int64 bbid = 1;
  // failed_step_name should be 'compile' for compile failures.
  string failed_step_name = 2;
}

message ListTestAnalysesRequest {
  // The project that the test analyses belong to.
  string project = 1 [ (google.api.field_behavior) = REQUIRED ];
  // Optional. The maximum number of analyses to be returned in the response.
  // The service may return fewer than this value.
  // If unspecified, at most 50 analyses will be returned.
  // The maximum value is 200; values above 200 will be coerced to 200.
  int32 page_size = 2;
  // Optional. A page token, received from a previous `ListTestAnalyses` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListTestAnalyses` must
  // match the call that provided the page token,
  // with the exception of page_size and page_token.
  string page_token = 3;
  // The fields to be included in the response.
  // By default, all fields are included.
  google.protobuf.FieldMask fields = 4;
}

message ListTestAnalysesResponse {
  // The test analyses corresponding to the ListTestAnalysesRequest.
  repeated TestAnalysis analyses = 1;
  // The token to send as `page_token` to retrieve the next page of analyses.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

message GetTestAnalysisRequest {
  // ID of the analysis.
  int64 analysis_id = 1 [ (google.api.field_behavior) = REQUIRED ];
  // The fields to be included in the response.
  // By default, all fields are included.
  google.protobuf.FieldMask fields = 2;
}

message TestAnalysis {
  // ID to identify this analysis.
  int64 analysis_id = 1;
  // Timestamp for the create time of the analysis.
  google.protobuf.Timestamp created_time = 2;
  // Timestamp for the start time of the analysis.
  google.protobuf.Timestamp start_time = 3;
  // Timestamp for the end time of the analysis.
  google.protobuf.Timestamp end_time = 4;
  // Result status of the analysis.
  AnalysisStatus status = 5;
  // Run status of the analysis.
  AnalysisRunStatus run_status = 6;
  // The verified culprit for the analysis.
  TestCulprit culprit = 7;
  // The builder that the analysis analyzed.
  buildbucket.v2.BuilderID builder = 8;
  // Test failures that the analysis analyzed.
  // The first item will be the primary failure, followed by other failures.
  // Bisection process will follow the path of the primary test failure.
  repeated TestFailure test_failures = 9;
  // The start commit of the regression range (exclusive).
  buildbucket.v2.GitilesCommit start_commit = 10;
  // The end commit of the regression range (inclusive).
  buildbucket.v2.GitilesCommit end_commit = 11;
  // The start failure rate of the failures.
  float start_failure_rate = 12;
  // The end failure rate of the failures.
  float end_failure_rate = 13;
  // Sample build bucket ID where the primary test failure failed.
  int64 sample_bbid = 14;
  // Nthsection result.
  TestNthSectionAnalysisResult nth_section_result = 15;
}

message TestFailure {
  // The ID of the test.
  string test_id = 1;
  // The variant hash of the test.
  string variant_hash = 2;
  // Hash to identify the branch in the source control.
  string ref_hash = 3;
  // The variant of the test.
  Variant variant = 4;
  // Whether the test failure was diverged from the primary test failure
  // during the bisection process.
  bool is_diverged = 5;
  // Whether the test failure is a primary failure or not.
  bool is_primary = 6;
  // Start hour of the test failure.
  google.protobuf.Timestamp start_hour = 7;
}

message TestNthSectionAnalysisResult {
  // The status of the nth-section analysis.
  AnalysisStatus status = 1;
  // The run status of the nth-section analysis.
  AnalysisRunStatus run_status = 2;
  // Timestamp for the start time of the nth-section analysis.
  google.protobuf.Timestamp start_time = 3;
  // Timestamp for the end time of the nth-section analysis.
  google.protobuf.Timestamp end_time = 4;
  // Optional, when status = RUNNING. This is the possible commit range of the
  // culprit. This will be updated as the nth-section progress.
  // This will only be available if nthsection is still running (not ended).
  RegressionRange remaining_nth_section_range = 5;
  // List of the reruns that have been run so far for the nth-section analysis.
  // The runs are sorted by the create timestamp.
  repeated TestSingleRerun reruns = 6;
  // The blame list of commits to run the nth-section analysis on.
  // The commits are sorted by recency, with the most recent commit first.
  BlameList blame_list = 7;
  // Optional, when nth-section has found a culprit.
  TestCulprit suspect = 8;
}

message TestSingleRerun {
  // Buildbucket ID of the rerun build.
  int64 bbid = 1;
  // Timestamp for the create time of the rerun.
  google.protobuf.Timestamp create_time = 2;
  // Timestamp for the start time of the rerun.
  google.protobuf.Timestamp start_time = 3;
  // Timestamp for the end time of the rerun.
  google.protobuf.Timestamp end_time = 4;
  // Timestamp when the rerun send the result to bisection from recipe.
  google.protobuf.Timestamp report_time = 5;
  // ID of the bot that runs the rerun.
  string bot_id = 6;
  // Result of the rerun.
  RerunTestResults rerun_result = 7;
  // Gitiles commit to do the rerun with.
  buildbucket.v2.GitilesCommit commit = 8;
  // Index of the commit to rerun within the blamelist, if this is an
  // nth-section rerun. We need to use a string instead of an int here because
  // 0 is a possible valid value but would get lost due to the "omitempty" flag
  // in the generated proto.
  // There is one case where the index is not populated (empty string). It is when
  // the culprit is the (last pass + 1) position, and this rerun is for parent commit
  // of the culprit verification. In such cases, the parent commit (last pass) is not found in the
  // blamelist (this blamelist is (last pass, first fail]). In such case, index will be "".
  string index = 9;
}

message RerunTestResults {
  repeated RerunTestSingleResult results = 1;
  // Status of the rerun.
  RerunStatus rerun_status = 2;
}

message RerunTestSingleResult {
  // Test ID of the result.
  string test_id = 1;
  // Variant hash of the result.
  string variant_hash = 2;
  // Number of expected results.
  int64 expected_count = 3;
  // Number of unexpected results.
  int64 unexpected_count = 4;
}

message TestSuspectVerificationDetails {
  // The status of the suspect verification.
  SuspectVerificationStatus status = 1;
  // The verification rerun build for the suspect commit.
  TestSingleRerun suspect_rerun = 2;
  // The verification rerun build for the parent commit of the suspect.
  TestSingleRerun parent_rerun = 3;
}

message TestCulprit {
  // The gitiles commit for the culprit.
  buildbucket.v2.GitilesCommit commit = 1;
  // The review URL for the culprit.
  string review_url = 2;
  // The review title for the culprit.
  string review_title = 3;
  // Actions we have taken with the culprit.
  // More than one action may be taken, for example, reverting the culprit and
  // commenting on the bug.
  repeated CulpritAction culprit_action = 4;
  // The details of suspect verification for the culprit.
  TestSuspectVerificationDetails verification_details = 5;
}

message BatchGetTestAnalysesRequest {
  // The LUCI project.
  string project = 1;
 // Identify a test failure.
 message TestFailureIdentifier {
   // Identify a test variant. All fields are required.
   // This represents the ongoing test failure of this test variant.
   string test_id = 1;
   string variant_hash = 2;
   string ref_hash = 3;
   // TODO: Add an optional source_position field in this proto.
   // This is the source position where a failure occurs.
   // See go/surface-bisection-and-changepoint-analysis-som.
 }
 // The response will only contain analyses which analyze failures in this list.
 // It is an error to request for more than 100 test failures.
  repeated TestFailureIdentifier test_failures = 2;

  // The fields to be included in the response.
  // By default, all fields are included.
  google.protobuf.FieldMask fields = 3;
}


message BatchGetTestAnalysesResponse {
 // Test analyses for each test failure in the order they were requested.
 // The test analysis will be null if the requested test failure has not been
 // analyzed by any bisection.
 repeated TestAnalysis test_analyses = 1;
}