go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/analysis/proto/v1/changepoints.proto

// Copyright 2024 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.v1;

option go_package = "go.chromium.org/luci/analysis/proto/v1;analysispb";

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

// This service currently only return changepoints which have an increase in unexpected verdict rate, aka. Regression.
// In the future, it may be extended for obtaining groups which have a decreased unexpected verdict rate aka. fixes.
service Changepoints {
  // Query the changepoint group summaries.
  // Currently this RPC only returns at most 1000 changepoint groups starting at the current week.
  // TODO: Add pagination to this RPC so that more changepoint history can be seen.
  rpc QueryChangepointGroupSummaries(QueryChangepointGroupSummariesRequest) returns (
    QueryChangepointGroupSummariesResponse) {};
  // Query the changepoints in a particular group.
  // TODO: Implement pagination, currently just return at most 1000 changepoints.
  rpc QueryChangepointsInGroup(QueryChangepointsInGroupRequest) returns (
    QueryChangepointsInGroupResponse) {}
}

message QueryChangepointGroupSummariesRequest {
  // The LUCI project. Mandatory field.
  string project = 1;
  // A filter to be applied to each changepoint in the groups.
  // If all changepoints in a group are filtered out, this group will not be returned.
  ChangepointPredicate predicate = 2;
}

// Represent a function Changepoint -> bool
message ChangepointPredicate {
  // The test id of this changepoint matches this prefix.
  string test_id_prefix = 1;

  // Specify a range. The unexpected verdict rate change on this changepoint needs to fall into this range.
  // Unexpected verdict rate change is calculated by (unexpected verdict rate after changepoint - unexpected verdict rate before changepoint). Negative number means unexpected verdict rate decreases, positive number means increases.
  // eg. {lower_bound:0.1, upper_bound:0.9} means keep changepoint which has a unexpected verdict rate increase >= 10% and <= 90%.
  NumericRange unexpected_verdict_rate_change_range = 2;
}

message QueryChangepointGroupSummariesResponse {
  // A list of changepoint group summaries.
  repeated ChangepointGroupSummary group_summaries = 1;
}

// Represent the summary of a changepoint group.
message ChangepointGroupSummary {
  // The canonical changepoint in the group. This is the changepoint with minimum (test_id, variant_hash, ref_hash, nominal_start_position) combination.
  Changepoint canonical_changepoint = 1;
  // Statistics of this group.
  ChangepointGroupStatistics statistics = 2;
}

message ChangepointGroupStatistics {
  // The number of test variant branches in this group.
  int32 count = 1;
  message RateDistribution {
    // Average unexpected verdict rate of all test variant branches in the group. This is a value between 0.0 and 1.0.
    // Consequently, this is an ‘average of averages’.
    float average = 1;
    message RateBuckets {
      // Counts the number of test variant branches with a unexpected verdict rate less than 5% (exclusive).
      int32 count_less_5_percent = 1;
      // Counts the number of test variant branches with a unexpected verdict rate greater than or equal to 5%, but less than 95%.
      int32 count_above_5_less_than_95_percent = 2;
      // Counts the number of test variant branches with a unexpected verdict rate equal to or greater than 95%.
      int32 count_above_95_percent = 3;
    }
    // Count the number of changepoint that fall into each rate bucket.
    RateBuckets buckets = 2;
  }

  // Unexpected verdict rate before the changepoint.
  // The per test variant branch, unexpected verdict rate is calculated as (count of unexpected verdict/count of all verdicts).
  RateDistribution unexpected_verdict_rate_before = 2;
  // Unexpected verdict rate after the changepoint.
  RateDistribution unexpected_verdict_rate_after = 3;
  // The current unexpected verdict rate.
  RateDistribution unexpected_verdict_rate_current = 4;

  // Unexpected verdict rate change is calculated by (unexpected verdict rate after changepoint - unexpected verdict rate before changepoint).
  // TODO: we need to add buckets for unexpected verdict rate decrease when we support grouping fixes. Unexpected verdict rate decrease will be represented as negative number.
  message RateChangeBuckets {
    // Counts the number of test variant branches which saw their unexpected verdict rate increase by between 0% (inclusive) and 20% (exclusive).
    int32 count_increased_0_to_20_percent = 1;
    // Counts the number of test variant branches which saw their unexpected verdict rate increase by between 20% (inclusive) and 50% (exclusive).
    int32 count_increased_20_to_50_percent = 2;
    // Counts the number of test variant branches which saw their unexpected verdict rate increase by between 50% (inclusive) or more.
    int32 count_increased_50_to_100_percent = 3;
  }
  // The amount of change in unexpected verdict rate before and after the changepoint.
  RateChangeBuckets unexpected_verdict_rate_change = 5;
}

message QueryChangepointsInGroupRequest {
  // The LUCI project. Mandatory field.
  string project = 1;
  // We consider two changepoints matches if
  //   * their test_id, variant_hash, ref_hash are exactly the same,
  //           AND
  //   *  nominal_start_position is within the other changepoint's 99% confidence interval (inclusive).
  // Most of the time there should be only one matching changepoint.
  // However, in rare cases adjacent segments can have an overlapping 99% confidence interval.
  // It makes it possible that more than one changepoint matches. In this case, we select the one with the closest nominal start position.
  message ChangepointIdentifier {
    string test_id = 1;
    string variant_hash = 2;
    string ref_hash = 3;
    int64 nominal_start_position = 4;
    // The nominal start hour of this changepoint in UTC.
    // This is used to locate a week in UTC (Saturday to Sunday) to generate changepoint groups.
    google.protobuf.Timestamp start_hour = 5;
  }

  // Identify a group with this changepoint. Mandatory field.
  ChangepointIdentifier group_key = 2;
  // A filter to be applied to each changepoint.
  ChangepointPredicate predicate = 3;
}

// TODO: Implement pagination, currently just return at most 1000 changepoints.
message QueryChangepointsInGroupResponse {
  // A list of changepoints in a group.
  repeated Changepoint changepoints = 1;
}


// Represent a changepoint of a test variant branch.
// Next ID: 15.
message Changepoint {
  // The LUCI Project. E.g. "chromium".
  string project = 1;
  // The identity of the test.
  string test_id = 2;
  // Hash of the variant, as 16 lowercase hexadecimal characters.
  // E.g. "96c68dc946ab4068".
  string variant_hash = 3;
  // 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 = 14;
  // Hash of the source branch, as 16 lowercase hexadecimal characters.
  string ref_hash = 4;
  // The branch in source control.
  luci.analysis.v1.SourceRef ref = 5;
  // The nominal start hour of this changepoint.
  google.protobuf.Timestamp start_hour = 9;
  // The lower bound of the starting changepoint position in a 99% two-tailed
  // confidence interval. Inclusive.
  int64 start_position_lower_bound_99th = 10;
  // The upper bound of the starting changepoint position in a 99% two-tailed
  // confidence interval. Inclusive.
  int64 start_position_upper_bound_99th = 11;
  // The nominal commit position at which the segment starts (inclusive).
  int64 nominal_start_position = 12;
  // The nominal commit position at which the previous segment ends (inclusive).
  int64 previous_segment_nominal_end_position = 13;
}