Rework job states

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/bufbuild/buf
-    rev: v1.54.0
+    rev: v1.57.2
     hooks:
     - id: buf-lint
     - id: buf-format

apis/workflows/v1/core.proto

@@ -29,31 +29,77 @@
   string name = 2;
   string trace_parent = 3;
   reserved 4;
-  // Whether the job has been canceled.
-  bool canceled = 5;
-  // The current state of the job.
-  JobState state = 6;
+  // Whether the job has been canceled. Deprecated, part of the job status.
+  bool canceled = 5 [deprecated = true];
+  // The current state of the job. Deprecated, use status instead.
+  LegacyJobState legacy_state = 6 [deprecated = true];
   // The time the job was submitted.
   google.protobuf.Timestamp submitted_at = 7;
-  // The time the job started running.
-  google.protobuf.Timestamp started_at = 8;
-  // The task' summaries of the job.
+  // The time the job started running. Deprecated, use execution_stats.first_task_started_at instead.
+  google.protobuf.Timestamp started_at = 8 [deprecated = true];
+  // A list of tasks of the job.
   repeated TaskSummary task_summaries = 9;
   // The automation that submitted the job.
   tilebox.v1.ID automation_id = 10;
   // A list of progress indicators for the job.
   repeated Progress progress = 11;
+  // The status of the job.
+  JobState state = 12;
+  // The execution stats of the job inferred from the tasks.
+  ExecutionStats execution_stats = 13;
 }
 
-// The state of a job.
-enum JobState {
-  JOB_STATE_UNSPECIFIED = 0;
+// ExecutionStats contains statistics about the execution of a job.
+message ExecutionStats {
+  // The time the first task of the job was started.
+  google.protobuf.Timestamp first_task_started_at = 1;
+  // The time the last task of the job was stopped.
+  google.protobuf.Timestamp last_task_stopped_at = 2;
+  // The total compute time of the job, as sum of all task compute times.
+  google.protobuf.Duration compute_time = 3;
+  // The elapsed time of the job (wall time), which is the time from first task started to last task stopped.
+  google.protobuf.Duration elapsed_time = 4;
+  // The parallelism factor of the job, which is the average number of tasks running at any given time.
+  double parallelism = 5;
+  // Total number of tasks of the job.
+  uint64 total_tasks = 6;
+  // Number of tasks by their state.
+  repeated TaskStateCount tasks_by_state = 7;
+}
+
+// TaskStateCount is a message specifying the number of tasks in a certain state.
+message TaskStateCount {
+  TaskState state = 1;
+  uint64 count = 2;
+}
+
+// The state of a job, deprecated in favor of JobState.
+enum LegacyJobState {
+  LEGACY_JOB_STATE_UNSPECIFIED = 0;
   // The job is queued and waiting to be run.
-  JOB_STATE_QUEUED = 1;
+  LEGACY_JOB_STATE_QUEUED = 1;
   // At least one task of the job has been started.
-  JOB_STATE_STARTED = 2;
+  LEGACY_JOB_STATE_STARTED = 2;
   // All tasks of the job have been completed.
-  JOB_STATE_COMPLETED = 3;
+  LEGACY_JOB_STATE_COMPLETED = 3;
+}
+
+// The state of a job, which is computed from the state of each of the jobs tasks combined with the information
+// if the job has been canceled or not.
+enum JobState {
+  JOB_STATE_UNSPECIFIED = 0;
+  // The job has been submitted, queued and waiting for its first task to be run.
+  JOB_STATE_SUBMITTED = 1;
+  // The job is running, i.e. at least one task is running.
+  JOB_STATE_RUNNING = 2;
+  // The job has started running, i.e. at least one task has been computed, but currently no tasks are running.
+  JOB_STATE_STARTED = 3;
+  // The job has completed successfully.
+  JOB_STATE_COMPLETED = 4;
+  // The job has failed.
+  JOB_STATE_FAILED = 5;
+  // The job has been canceled on user request.
+  JOB_STATE_CANCELED = 6;
 }
 
 // A summary of a task. Mainly used in the Console.
@@ -102,20 +148,18 @@
 }
 
 // The state of a task.
 enum TaskState {
   TASK_STATE_UNSPECIFIED = 0;
   // The task is queued and waiting to be run.
   TASK_STATE_QUEUED = 1;
   // The task is currently running on some task runner.
   TASK_STATE_RUNNING = 2;
   // The task has been computed and the output is available.
   // If the task also has no more outstanding children, it is considered COMPLETED.
   TASK_STATE_COMPUTED = 3;
   // The task has failed.
   TASK_STATE_FAILED = 4;
-  // The task has been cancelled due to user request.
-  TASK_STATE_CANCELLED = 5;
 }
 
 // An identifier for a task.
 message TaskIdentifier {