pinpoint/proto/v1/service.proto - buildbot - Git at Google

 syntax = "proto3";

 // Working in progress protobuf and service definition.
 //
 package pinpoint.v1;
 option go_package = "go.skia.org/infra/pinpoint/proto/v1;pinpointpb";

 import "google/api/annotations.proto";
 import "google/protobuf/timestamp.proto";

 // The direct mirror of the existing bisect request in catapult.
 // https://chromium.googlesource.com/catapult.git/+/09398d/
 // dashboard/dashboard/pinpoint/models/job.py#339
 //
 // Note, some fields are only for backward-compatibility only.
 message ScheduleBisectRequest {
 	string comparison_mode = 1;
 	string start_git_hash = 2;
 	string end_git_hash = 3;

 	// The builder/bot configuration name, this usually specifies the builder that can trigger
 	// the build.
 	string configuration = 4;

 	// The Chrome perf benchmark test target.
 	// All the targets are generated from here:
 	// https://chromium.googlesource.com/chromium/src/+/52c8723/tools/perf/core/perf_data_generator.py
 	string benchmark = 5;

 	// https://chromium.googlesource.com/catapult.git/+/e8367e6/telemetry
 	// The story is usually a test case that runs a set of actions in a certain scenario, and
 	// collects performance histogram data to analyze.
 	string story = 6;
 	string chart = 7;
 	string statistic = 8;

 	// Comparison Magnitude is the expected absolute difference of a potential regression.
 	string comparison_magnitude = 9;

 	// The Change (Commits + Patch) to apply to every change for all the subsequence runs.
 	string pin = 10;

 	// The Monorail project ID.
 	string project = 11;

 	// The monorail issue id number to post updates to.
 	string bug_id = 12;

 	// The user email who triggers the job.
 	string user = 13;

 	// The mechanism in which benchmark measurements are aggregated by.
 	// One of sum, mean, min, max count, and std.
 	string aggregation_method = 14;

 	// StoryTags is a comma delimited string of tags to pass for the story.
 	// For example, "all", "representative_win_desktop" or "2019,2018".
 	string story_tags = 15;

 	// The minimum number of test iterations run.
 	string initial_attempt_count = 16;

 	// A JSON string encoded key-value pairs used to filter the Jobs listings.
 	string tags = 17;

 	// The improvement direction of the measurement.
 	// Is either Up, Down, or Unknown.
 	string improvement_direction = 18;
 }

 message QueryBisectRequest {
 	string job_id = 1;
 }

 message CancelJobRequest {
 	string job_id = 1;
 	string reason = 2;
 }

 message CancelJobResponse {
 	string job_id = 1;
 	string state = 2;
 }

 message Commit {
 	string git_hash = 1;
 	string repository = 2;
 	string url = 3;
 	string author = 4;
 	google.protobuf.Timestamp created = 5;
 	string subject = 6;
 	string message = 7;
 	string commit_branch = 8;
 	int32 commit_position = 9;
 	string review_url = 10;
 	string change_id = 11;
 }

 message CombinedCommit {
 	Commit main = 1;
 	repeated Commit modified_deps = 2;
 }

 // Culprit contains the culprit commit and also the commit prior to the culprit.
 // Culprit verification needs to verify there is a real regression between the culprit
 // the the prior commit (A-1 vs A). Bisection writes this information as part of the
 // culprit finder workflow.
 message Culprit {
 	CombinedCommit prior = 1; // the commit prior to the culprit
  	CombinedCommit culprit = 2; // the culprit commit
 }

 message BisectExecution {
 	string job_id = 1;
 	// TODO(b/322203189): replace this with detailed_culprit. This field is used by the
 	// catapult bisect UI write.
 	repeated CombinedCommit culprits = 2;

 	// Although this field is used only in culprit verification, bisection needs to pass
 	// the commit prior to the culprit to the culprit verification step.
 	repeated Culprit detailed_culprits = 3;
 }

 // SchedulePairwiseRequest contains the input to schedule a pairwise job used
 // in regression and culprit verification. This request uses a subset of the params
 // used in Pinpoint try jobs. Pairwise can check for regressions between two commits
 // that are located in repos outside of chromium/src. This use case is particularly
 // important for verifying culprits that are located in DEPS rolls.
 //
 // The params used are defined here:
 // https://source.chromium.org/chromium/chromium/src/+/main:third_party/catapult/dashboard/
 // dashboard/services/workflow_service.py;drc=2b42d43ff4989182d28de40ad4ed0dc82356c0f7;l=35
 // The params are defined based off of the keys used in catapult.
 // TODO(b/346836299): Add user-facing try job request params to this request.
 // i.e. extra-browser-args
 message SchedulePairwiseRequest {
 	CombinedCommit start_commit = 1;
 	CombinedCommit end_commit = 2;

 	// The builder/bot configuration name, this usually specifies the builder that can trigger
 	// the build.
 	string configuration = 3 [json_name = "bot_name"];

 	// The Chrome perf benchmark test target.
 	string benchmark = 4;

 	// https://chromium.googlesource.com/catapult.git/+/e8367e6/telemetry
 	// The story is usually a test case that runs a set of actions in a certain scenario, and
 	// collects performance histogram data to analyze.
 	string story = 5;
 	string chart = 6 [json_name = "measurement"];
 	string statistic = 7; // not included in the catapult request, which might be a mistake
 	string target = 8; // probably unnecessary, we can infer this

 	// The Monorail project ID.
 	string project = 9;

 	// The buganizer issue id number to post updates to.
 	string bug_id = 10;

 	// The minimum number of test iterations run. Default is 30
 	string initial_attempt_count = 11;

 	// The improvement direction of the measurement.
 	// Is either Up, Down, or Unknown.
 	string improvement_direction = 12 [json_name = "improvement_dir"];
 }

 message PairwiseExecution {
 	// significant regression / culprit if true
 	bool significant = 1;
 	string job_id = 2;
 	message WilcoxonResult {
 		double p_value = 1;
 		double confidence_interval_lower = 2;
 		double confidence_interval_higher = 3;
 		double control_median = 4;
 		double treatment_median = 5;
 	}
 	WilcoxonResult statistic = 3;

 	// The culprit is only populated on culprit verification workflows
 	// and if the result is significant
 	CombinedCommit culprit = 4;
 }

 // ScheduleCulpritFinderRequest contains the input to schedule an E2E anomaly to culprits
 // workflow. This workflow consists of a regression verification step, a bisection to find
 // culprits, and a culprit verification step.
 // This workflow is also known as the sandwich verification workflow.
 // This workflow assumes that the culprit is detected on chromium/src and does not
 // support start and end git hashes on other repos.
 message ScheduleCulpritFinderRequest {
 	string start_git_hash = 1;
 	string end_git_hash = 2;

 	// The builder/bot configuration name.
 	string configuration = 3 [json_name = "bot_name"];

 	// The Chrome perf benchmark test target.
 	string benchmark = 4;

 	// https://chromium.googlesource.com/catapult.git/+/e8367e6/telemetry
 	// The story is usually a test case that runs a set of actions in a certain scenario, and
 	// collects performance histogram data to analyze.
 	string story = 5;
 	string chart = 6 [json_name = "measurement"];

 	// The statistic, if there is one, aggregates measurement values into a single data point.
 	string statistic = 7;

 	// The improvement direction of the measurement.
 	// Is either Up, Down, or Unknown.
 	string improvement_direction = 8 [json_name = "improvement_dir"];

 	// The comparison magnitude is the expected absolute difference of a potential regression.
 	// This parameter is used in bisection.
 	string comparison_magnitude = 9;

 	// The buganizer issue id number to post updates to. This is a legacy feature.
 	string bug_id = 10;
 }

 message CulpritFinderExecution {
 	// If true, regression_verified means there is a regression
 	bool regression_verified = 1;

 	repeated CombinedCommit culprits = 2;
 }

 // See LegacyJobResponse below
 message LegacyJobRequest {
 	string job_id = 1;
 }

 // This is a direct mapping from /api/job in catapult.
 //
 // This is backward compatible support before the service in catapult is completely shut down.
 // Note that there is not schema definition so the output structure is more or less
 // a guess from the response. Example output:
 // https://pinpoint-dot-chromeperf.appspot.com/api/job/102beaa5ee0000?o=STATE&?o=ESTIMATE
 message LegacyJobResponse {
 	string job_id = 1;
 	string configuration = 2;
 	string results_url = 3;
 	int32 improvement_direction = 4;

 	message Argument {
 		string comparison_mode = 1;
 		string target = 2;
 		string start_git_hash = 3;
 		string end_git_hash = 4;
 		string trace = 5;
 		map<string,string> tags = 6;
 		int32 initial_attempt_count = 7;
 		string configuration = 8;
 		string benchmark = 9;
 		string story = 10;
 		string story_tags = 11;
 		string chart = 12;
 		string statistic = 13;
 		double comparison_magnitude = 14;
 		string extra_test_args = 15;
 		string pin = 16;
 		string project = 17;
 		string bug_id = 18;
 		string batch_id = 19;
 	}
 	Argument arguments = 5;

 	string bug_id = 6;
 	string project = 7;
 	string comparison_mode = 8;
 	string name = 9;
 	string user = 10;
 	google.protobuf.Timestamp created = 11;
 	google.protobuf.Timestamp updated = 12;
 	google.protobuf.Timestamp started_time = 13;
 	int32 difference_count = 14;
 	string exception = 15;
 	string status = 16;
 	string cancel_reason = 17;
 	string batch_id = 18;
 	repeated string bots = 19;
 	string metric = 20;
 	repeated string quests = 21;

 	message State {
 		message Change {
 			repeated Commit commits = 1;
 		}
 		Change change = 1;

 		message Attempt {
 			message Execution {
 				bool completed = 1;
 				string exception = 2;

 				message Detail {
 					string key = 1;
 					string value = 2;
 					string url = 3;
 				}
 				repeated Detail details = 3;
 			}
 			repeated Execution executions = 1;

 			// This key is not actually supported by Catapult's response here, but
 			// the values of each attempt is needed to populate data back on the UI.
 			repeated double result_values = 2;
 		}
 		repeated Attempt attempts = 2;

 		message Comparison {
 			string next = 1;
 			string prev = 2;
 		}
 		Comparison comparisons = 3;
 		repeated double values = 4;
 	}
 	repeated State state = 22;
 	string skia_workflow_url = 23;
 }

 service Pinpoint {
 	rpc ScheduleBisection(ScheduleBisectRequest) returns (BisectExecution) {
 		option (google.api.http) = {
 			post: "/pinpoint/v1/bisection"
 				additional_bindings {
 					post: "/pinpoint/v1/schedule"
 				}
 		};
 	}

 	rpc CancelJob(CancelJobRequest) returns (CancelJobResponse) {
 		option (google.api.http) = {
 			get: "/pinpoint/v1/cancel"
 		};
 	}

 	rpc QueryBisection(QueryBisectRequest) returns (BisectExecution) {
 		option (google.api.http) = {
 			get: "/pinpoint/v1/query"
 		};
 	}

 	rpc LegacyJobQuery(LegacyJobRequest) returns (LegacyJobResponse) {
 		option (google.api.http) = {
 			get: "/pinpoint/v1/legacy-job"
 		};
 	}

 	rpc SchedulePairwise(SchedulePairwiseRequest) returns (PairwiseExecution) {
 		option (google.api.http) = {
 			post: "/pinpoint/v1/pairwise"
 		};
 	}

 	rpc ScheduleCulpritFinder(ScheduleCulpritFinderRequest) returns (CulpritFinderExecution) {
 		option (google.api.http) = {
 			post: "/pinpoint/v1/culprit-finder"
 		};
 	}
 }
	syntax = "proto3";

	// Working in progress protobuf and service definition.
	//
	package pinpoint.v1;
	option go_package = "go.skia.org/infra/pinpoint/proto/v1;pinpointpb";

	import "google/api/annotations.proto";
	import "google/protobuf/timestamp.proto";

	// The direct mirror of the existing bisect request in catapult.
	// https://chromium.googlesource.com/catapult.git/+/09398d/
	// dashboard/dashboard/pinpoint/models/job.py#339
	//
	// Note, some fields are only for backward-compatibility only.
	message ScheduleBisectRequest {
	string comparison_mode = 1;
	string start_git_hash = 2;
	string end_git_hash = 3;

	// The builder/bot configuration name, this usually specifies the builder that can trigger
	// the build.
	string configuration = 4;

	// The Chrome perf benchmark test target.
	// All the targets are generated from here:
	// https://chromium.googlesource.com/chromium/src/+/52c8723/tools/perf/core/perf_data_generator.py
	string benchmark = 5;

	// https://chromium.googlesource.com/catapult.git/+/e8367e6/telemetry
	// The story is usually a test case that runs a set of actions in a certain scenario, and
	// collects performance histogram data to analyze.
	string story = 6;
	string chart = 7;
	string statistic = 8;

	// Comparison Magnitude is the expected absolute difference of a potential regression.
	string comparison_magnitude = 9;

	// The Change (Commits + Patch) to apply to every change for all the subsequence runs.
	string pin = 10;

	// The Monorail project ID.
	string project = 11;

	// The monorail issue id number to post updates to.
	string bug_id = 12;

	// The user email who triggers the job.
	string user = 13;

	// The mechanism in which benchmark measurements are aggregated by.
	// One of sum, mean, min, max count, and std.
	string aggregation_method = 14;

	// StoryTags is a comma delimited string of tags to pass for the story.
	// For example, "all", "representative_win_desktop" or "2019,2018".
	string story_tags = 15;

	// The minimum number of test iterations run.
	string initial_attempt_count = 16;

	// A JSON string encoded key-value pairs used to filter the Jobs listings.
	string tags = 17;

	// The improvement direction of the measurement.
	// Is either Up, Down, or Unknown.
	string improvement_direction = 18;
	}

	message QueryBisectRequest {
	string job_id = 1;
	}

	message CancelJobRequest {
	string job_id = 1;
	string reason = 2;
	}

	message CancelJobResponse {
	string job_id = 1;
	string state = 2;
	}

	message Commit {
	string git_hash = 1;
	string repository = 2;
	string url = 3;
	string author = 4;
	google.protobuf.Timestamp created = 5;
	string subject = 6;
	string message = 7;
	string commit_branch = 8;
	int32 commit_position = 9;
	string review_url = 10;
	string change_id = 11;
	}

	message CombinedCommit {
	Commit main = 1;
	repeated Commit modified_deps = 2;
	}

	// Culprit contains the culprit commit and also the commit prior to the culprit.
	// Culprit verification needs to verify there is a real regression between the culprit
	// the the prior commit (A-1 vs A). Bisection writes this information as part of the
	// culprit finder workflow.
	message Culprit {
	CombinedCommit prior = 1; // the commit prior to the culprit
	CombinedCommit culprit = 2; // the culprit commit
	}

	message BisectExecution {
	string job_id = 1;
	// TODO(b/322203189): replace this with detailed_culprit. This field is used by the
	// catapult bisect UI write.
	repeated CombinedCommit culprits = 2;

	// Although this field is used only in culprit verification, bisection needs to pass
	// the commit prior to the culprit to the culprit verification step.
	repeated Culprit detailed_culprits = 3;
	}

	// SchedulePairwiseRequest contains the input to schedule a pairwise job used
	// in regression and culprit verification. This request uses a subset of the params
	// used in Pinpoint try jobs. Pairwise can check for regressions between two commits
	// that are located in repos outside of chromium/src. This use case is particularly
	// important for verifying culprits that are located in DEPS rolls.
	//
	// The params used are defined here:
	// https://source.chromium.org/chromium/chromium/src/+/main:third_party/catapult/dashboard/
	// dashboard/services/workflow_service.py;drc=2b42d43ff4989182d28de40ad4ed0dc82356c0f7;l=35
	// The params are defined based off of the keys used in catapult.
	// TODO(b/346836299): Add user-facing try job request params to this request.
	// i.e. extra-browser-args
	message SchedulePairwiseRequest {
	CombinedCommit start_commit = 1;
	CombinedCommit end_commit = 2;

	// The builder/bot configuration name, this usually specifies the builder that can trigger
	// the build.
	string configuration = 3 [json_name = "bot_name"];

	// The Chrome perf benchmark test target.
	string benchmark = 4;

	// https://chromium.googlesource.com/catapult.git/+/e8367e6/telemetry
	// The story is usually a test case that runs a set of actions in a certain scenario, and
	// collects performance histogram data to analyze.
	string story = 5;
	string chart = 6 [json_name = "measurement"];
	string statistic = 7; // not included in the catapult request, which might be a mistake
	string target = 8; // probably unnecessary, we can infer this

	// The Monorail project ID.
	string project = 9;

	// The buganizer issue id number to post updates to.
	string bug_id = 10;

	// The minimum number of test iterations run. Default is 30
	string initial_attempt_count = 11;

	// The improvement direction of the measurement.
	// Is either Up, Down, or Unknown.
	string improvement_direction = 12 [json_name = "improvement_dir"];
	}

	message PairwiseExecution {
	// significant regression / culprit if true
	bool significant = 1;
	string job_id = 2;
	message WilcoxonResult {
	double p_value = 1;
	double confidence_interval_lower = 2;
	double confidence_interval_higher = 3;
	double control_median = 4;
	double treatment_median = 5;
	}
	WilcoxonResult statistic = 3;

	// The culprit is only populated on culprit verification workflows
	// and if the result is significant
	CombinedCommit culprit = 4;
	}

	// ScheduleCulpritFinderRequest contains the input to schedule an E2E anomaly to culprits
	// workflow. This workflow consists of a regression verification step, a bisection to find
	// culprits, and a culprit verification step.
	// This workflow is also known as the sandwich verification workflow.
	// This workflow assumes that the culprit is detected on chromium/src and does not
	// support start and end git hashes on other repos.
	message ScheduleCulpritFinderRequest {
	string start_git_hash = 1;
	string end_git_hash = 2;

	// The builder/bot configuration name.
	string configuration = 3 [json_name = "bot_name"];

	// The Chrome perf benchmark test target.
	string benchmark = 4;

	// https://chromium.googlesource.com/catapult.git/+/e8367e6/telemetry
	// The story is usually a test case that runs a set of actions in a certain scenario, and
	// collects performance histogram data to analyze.
	string story = 5;
	string chart = 6 [json_name = "measurement"];

	// The statistic, if there is one, aggregates measurement values into a single data point.
	string statistic = 7;

	// The improvement direction of the measurement.
	// Is either Up, Down, or Unknown.
	string improvement_direction = 8 [json_name = "improvement_dir"];

	// The comparison magnitude is the expected absolute difference of a potential regression.
	// This parameter is used in bisection.
	string comparison_magnitude = 9;

	// The buganizer issue id number to post updates to. This is a legacy feature.
	string bug_id = 10;
	}

	message CulpritFinderExecution {
	// If true, regression_verified means there is a regression
	bool regression_verified = 1;

	repeated CombinedCommit culprits = 2;
	}

	// See LegacyJobResponse below
	message LegacyJobRequest {
	string job_id = 1;
	}

	// This is a direct mapping from /api/job in catapult.
	//
	// This is backward compatible support before the service in catapult is completely shut down.
	// Note that there is not schema definition so the output structure is more or less
	// a guess from the response. Example output:
	// https://pinpoint-dot-chromeperf.appspot.com/api/job/102beaa5ee0000?o=STATE&?o=ESTIMATE
	message LegacyJobResponse {
	string job_id = 1;
	string configuration = 2;
	string results_url = 3;
	int32 improvement_direction = 4;

	message Argument {
	string comparison_mode = 1;
	string target = 2;
	string start_git_hash = 3;
	string end_git_hash = 4;
	string trace = 5;
	map<string,string> tags = 6;
	int32 initial_attempt_count = 7;
	string configuration = 8;
	string benchmark = 9;
	string story = 10;
	string story_tags = 11;
	string chart = 12;
	string statistic = 13;
	double comparison_magnitude = 14;
	string extra_test_args = 15;
	string pin = 16;
	string project = 17;
	string bug_id = 18;
	string batch_id = 19;
	}
	Argument arguments = 5;

	string bug_id = 6;
	string project = 7;
	string comparison_mode = 8;
	string name = 9;
	string user = 10;
	google.protobuf.Timestamp created = 11;
	google.protobuf.Timestamp updated = 12;
	google.protobuf.Timestamp started_time = 13;
	int32 difference_count = 14;
	string exception = 15;
	string status = 16;
	string cancel_reason = 17;
	string batch_id = 18;
	repeated string bots = 19;
	string metric = 20;
	repeated string quests = 21;

	message State {
	message Change {
	repeated Commit commits = 1;
	}
	Change change = 1;

	message Attempt {
	message Execution {
	bool completed = 1;
	string exception = 2;

	message Detail {
	string key = 1;
	string value = 2;
	string url = 3;
	}
	repeated Detail details = 3;
	}
	repeated Execution executions = 1;

	// This key is not actually supported by Catapult's response here, but
	// the values of each attempt is needed to populate data back on the UI.
	repeated double result_values = 2;
	}
	repeated Attempt attempts = 2;

	message Comparison {
	string next = 1;
	string prev = 2;
	}
	Comparison comparisons = 3;
	repeated double values = 4;
	}
	repeated State state = 22;
	string skia_workflow_url = 23;
	}

	service Pinpoint {
	rpc ScheduleBisection(ScheduleBisectRequest) returns (BisectExecution) {
	option (google.api.http) = {
	post: "/pinpoint/v1/bisection"
	additional_bindings {
	post: "/pinpoint/v1/schedule"
	}
	};
	}

	rpc CancelJob(CancelJobRequest) returns (CancelJobResponse) {
	option (google.api.http) = {
	get: "/pinpoint/v1/cancel"
	};
	}

	rpc QueryBisection(QueryBisectRequest) returns (BisectExecution) {
	option (google.api.http) = {
	get: "/pinpoint/v1/query"
	};
	}

	rpc LegacyJobQuery(LegacyJobRequest) returns (LegacyJobResponse) {
	option (google.api.http) = {
	get: "/pinpoint/v1/legacy-job"
	};
	}

	rpc SchedulePairwise(SchedulePairwiseRequest) returns (PairwiseExecution) {
	option (google.api.http) = {
	post: "/pinpoint/v1/pairwise"
	};
	}

	rpc ScheduleCulpritFinder(ScheduleCulpritFinderRequest) returns (CulpritFinderExecution) {
	option (google.api.http) = {
	post: "/pinpoint/v1/culprit-finder"
	};
	}
	}