go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/analysis/internal/clustering/proto/failure.proto

// Copyright 2022 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.analysis.internal.clustering;

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "go.chromium.org/luci/analysis/proto/v1/common.proto";
import "go.chromium.org/luci/analysis/proto/v1/sources.proto";
import "go.chromium.org/luci/analysis/proto/v1/failure_reason.proto";

option go_package = "go.chromium.org/luci/analysis/internal/clustering/proto;clusteringpb";

// Chunk is a set of unexpected test failures which are processed together
// for efficiency.
// Serialised and stored in GCS.
message Chunk {
  repeated Failure failures = 1;
}

// LUCI Analysis internal representation of an unexpected test failure.
message Failure {
  // The identity of the test result, as defined by the source system.
  luci.analysis.v1.TestResultId test_result_id = 1;

  // Timestamp representing the start of the data retention period. This acts
  // as the partitioning key in time/date-partitioned tables.
  google.protobuf.Timestamp partition_time = 2;

  // The one-based index of this failure within the chunk. Assigned by
  // LUCI Analysis ingestion.
  int64 chunk_index = 3;

  // Security realm of the test result.
  // For test results from ResultDB, this must be set. The format is
  // "{LUCI_PROJECT}:{REALM_SUFFIX}", for example "chromium:ci".
  string realm = 4;

  // The unique identifier of the test.
  // For test results from ResultDB, see luci.resultdb.v1.TestResult.test_id.
  string test_id = 5;

  // key:value pairs to specify the way of running a particular test.
  // e.g. a specific bucket, builder and a test suite.
  luci.analysis.v1.Variant variant = 6;

  // Metadata key value pairs for this test result.
  // It might describe this particular execution or the test case.
  // A key can be repeated.
  repeated luci.analysis.v1.StringPair tags = 25;

  // Hash of the variant.
  // hex(sha256(''.join(sorted('%s:%s\n' for k, v in variant.items())))).
  string variant_hash = 7;

  // A failure reason describing why the test failed.
  luci.analysis.v1.FailureReason failure_reason = 8;

  // The bug tracking component corresponding to this test case, as identified
  // by the test results system. If no information is available, this is
  // unset.
  luci.analysis.v1.BugTrackingComponent bug_tracking_component = 9;

  // The point in time when the test case started to execute.
  google.protobuf.Timestamp start_time = 10;

  // The amount of time the test case took to execute.
  google.protobuf.Duration duration = 11;

  reserved 12;

  reserved 24;

  // The exonerations applied to the test verdict.
  // An empty list indicates the test verdict this test result was a part of
  // was not exonerated.
  repeated TestExoneration exonerations = 26;

  // The presubmit run the test result was a part of (if any).
  PresubmitRun presubmit_run = 27;

  // The status of the build that contained this test result. Can be used
  // to filter incomplete results (e.g. where build was cancelled or had
  // an infra failure). Can also be used to filter builds with incomplete
  // exonerations (e.g. build succeeded but some tests not exonerated).
  // This is the build corresponding to ingested_invocation_id.
  luci.analysis.v1.BuildStatus build_status = 28;

  // Whether the build was critical to a presubmit run succeeding.
  // If the build was not part of a presubmit run, this is unset.
  optional bool build_critical = 29;

  // The unsubmitted changelists that were tested (if any).
  // Changelists are sorted in ascending (host, change, patchset) order.
  // Up to 10 changelists are captured.
  repeated luci.analysis.v1.Changelist changelists = 23;

  // The invocation from which this test result was ingested. This is
  // the top-level invocation that was ingested, an "invocation" being
  // a container of test results as identified by the source test result
  // system.
  //
  // For ResultDB, LUCI Analysis ingests invocations corresponding to
  // buildbucket builds.
  //
  // All test results ingested from the same invocation (i.e. with the
  // same ingested_invocation_id) will have the same partition time.
  string ingested_invocation_id = 14;

  // The zero-based index for this test result, in the sequence of the
  // ingested invocation's results for this test variant. Within the sequence,
  // test results are ordered by start_time and then by test result ID.
  // The first test result is 0, the last test result is
  // ingested_invocation_result_count - 1.
  int64 ingested_invocation_result_index = 15;

  // The number of test results having this test variant in the ingested
  // invocation.
  int64 ingested_invocation_result_count = 16;

  // Is the ingested invocation blocked by this test variant? This is
  // only true if all (non-skipped) test results for this test variant
  // (in the ingested invocation) are unexpected failures.
  //
  // Exoneration does not factor into this value; check exonerations
  // to see if the impact of this ingested invocation being blocked was
  // mitigated by exoneration.
  bool is_ingested_invocation_blocked = 17;

  // The identifier of the test run the test ran in. Test results in different
  // test runs are generally considered independent as they should be unable
  // to leak state to one another.
  //
  // In Chrome and Chrome OS, a test run logically corresponds to a swarming
  // task that runs tests, but this ID is not necessarily the ID of that
  // task, but rather any other ID that is unique per such task.
  //
  // If test result system is ResultDB, this is the ID of the ResultDB
  // invocation the test result was immediately contained within, not including
  // any "invocations/" prefix.
  string test_run_id = 18;

  // The zero-based index for this test result, in the sequence of results
  // having this test variant and test run. Within the sequence, test
  // results are ordered by start_time and then by test result ID.
  // The first test result is 0, the last test result is
  // test_run_result_count - 1.
  int64 test_run_result_index = 19;

  // The number of test results having this test variant and test run.
  int64 test_run_result_count = 20;

  // Is the test run blocked by this test variant? This is only true if all
  // (non-skipped) test results for this test variant (in the test run)
  // are unexpected failures.
  //
  // Exoneration does not factor into this value; check exonerations
  // to see if the impact of this test run being blocked was
  // mitigated by exoneration.
  bool is_test_run_blocked = 21;

  // The code sources tested, if known.
  luci.analysis.v1.Sources sources = 30;

  // The gardener rotations the build is a part of. Corresponds to the
  // `sheriff_rotations` field of the build input properties.
  repeated string build_gardener_rotations = 31;

  // Information about the test variant-branch the result is from.
  TestVariantBranch test_variant_branch = 32;

  // Next ID: 33.
}

// Statistics about the (test,variant,ref) the verdict is from.
message TestVariantBranch {
  // The counts of verdicts observed for this (test, variant, source ref)
  // with a partition time equal or less than the partition time of this
  // verdict. This figure only considers verdicts ingested by LUCI Analysis
  // prior to this verdict.
  // Hourly bucketing is used internally, so data is aligned to hour
  // boundaries.

  // The number of flaky verdicts in the preceding 24 hours. A verdict
  // is considered flaky for this count if it has both expected and
  // unexpected test results (excluding skips). Whether the verdict
  // was exonerated is irrelevant.
  int64 flaky_verdicts_24h = 1;

  // The number of unexpected verdicts in the preceding 24 hours. A verdict
  // is unexpected for this count if has only unexpected test results
  // (excluding skips). Whether the verdict was exonerated is irrelevant.
  int64 unexpected_verdicts_24h = 2;

  // The total number of verdicts in the preceding 24 hours, excluding
  // verdicts with only skipped test results.
  int64 total_verdicts_24h = 3;
}

// LUCI Analysis internal representation of a test exoneration.
message TestExoneration {
  // The machine-readable reason for the exoneration.
  luci.analysis.v1.ExonerationReason reason = 1;
}

// LUCI Analysis internal representation of a presubmit run (e.g. LUCI CV Run).
message PresubmitRun {
  // Identity of the presubmit run that contains this test result.
  // This should be unique per "CQ+1"/"CQ+2" attempt on gerrit.
  //
  // One presumbit run MAY have many ingested invocation IDs (e.g. for its
  // various tryjobs), but every ingested invocation ID only ever has one
  // presubmit run ID (if any).
  //
  // All test results for the same presubmit run will have one
  // partition_time.
  //
  // If the test result was not collected as part of a presubmit run,
  // this is unset.
  luci.analysis.v1.PresubmitRunId presubmit_run_id = 1;

  // The owner of the presubmit run (if any).
  // This is the owner of the CL on which CQ+1/CQ+2 was clicked
  // (even in case of presubmit run with multiple CLs).
  // There is scope for this field to become an email address if privacy
  // approval is obtained, until then it is "automation" (for automation
  // service accounts) and "user" otherwise.
  string owner = 2;

  // The mode of the presubmit run. E.g. DRY_RUN, FULL_RUN, QUICK_DRY_RUN.
  luci.analysis.v1.PresubmitRunMode mode = 3;

  // The presubmit run's ending status. E.g. SUCCESS, FAILURE, CANCELED.
  luci.analysis.v1.PresubmitRunStatus status = 4;
}