bisection/proto/culprit_detection.proto

syntax = "proto3";

option go_package = "go.skia.org/infra/bisection/go/proto";

service CulpritDetection {
  // GetPerformanceDifference determines whether two changes are performantly different.
  //
  // Performance differences are used to find culprits for performance metrics.
  // Thus, a performance difference indicates some performance regression.
  // See https://chromium.googlesource.com/chromium/src/+/HEAD/docs/speed/bisects.md
  // for more details.
  rpc GetPerformanceDifference(GetPerformanceDifferenceRequest)
      returns (GetPerformanceDifferenceResponse) {}
}

enum State {
  // The state is unknown when the calculated p-value is in between the low and high
  // thresholds. This usually indicates that more samples are required.
  UNKNOWN = 0;

  // The state is different when the calculated p-value is lower than or equal to the
  // low threshold. This indicates that the samples are unlikely to come from the same
  // distribution and are therefore liklely different.
  DIFFERENT = 1;

  // The state is the same when the calculated p-value is greater than the high
  // threshold. This indicates that the samples are unlikely to come from distributions
  // that differ by the given comparison magnitude.
  SAME = 2;
}

message RequestedDifference {
  // The estimated size of the regression to search for. Smaller magnitudes generally
  // require more samples.
  //
  // The comparsion magnitude is used to calculate the upper (high) threshold.
  //
  // For functional differences, the comparison magnitude refers to the failure rate, and
  // is expected to be of a value between 0.0 and 1.0.
  // Comparison magnitude defaults to 0.5 if undefined.
  //
  // For performance differences, the comparison magnitude refers to the size of the
  // performance difference, and is expected to be of a value between 0.0 and 4.0.
  // Smaller magnitudes generally require more samples.
  // Comparison magnitude defaults to 1.0 if undefined.
  double comparison_magnitude = 1;

  // If the calculated p-value is greater than this high threshold, the two samples are
  // determined to come from the same distribution.
  //
  // Setting this will override the high threshold that's usually calculated using the
  // comparison magnitude.
  double high_threshold = 2;

  // The traditional significance threshold. If the calculated p-value is lower than this
  // lower threshold, the two samples are determined to come from different
  // distributions. This defaults to a value of 0.01.
  double low_threshold = 3;
}

message GetPerformanceDifferenceRequest {
  // Values for performance differences are doubles, which usually refer to the
  // histogram sample values.
  repeated double samples_a = 1;

  repeated double samples_b = 2;

  RequestedDifference difference = 3;
}

message GetPerformanceDifferenceResponse {
  State state = 1;

  // The calculated p-value used to determine the state.
  double p_value = 2;

  // The low threshold used as part of the calculation.
  double low_threshold = 3;

  // The high threshold used as part of the calculation.
  double high_threshold = 4;
}