feat(taskprocessing): add occ commands to list tasks and compute stats

Signed-off-by: Julien Veyssier <julien-nc@posteo.net>

core/Command/TaskProcessing/ListCommand.php

@@ -0,0 +1,84 @@
+<?php
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OC\Core\Command\TaskProcessing;
+
+use OC\Core\Command\Base;
+use OCP\TaskProcessing\IManager;
+use OCP\TaskProcessing\Task;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class ListCommand extends Base {
+	public function __construct(
+		protected IManager $taskProcessingManager,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure() {
+		$this
+			->setName('taskprocessing:task:list')
+			->setDescription('list tasks')
+			->addOption(
+				'userIdFilter',
+				'u',
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks for one user ID'
+			)
+			->addOption(
+				'type',
+				't',
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks for one task type'
+			)
+			->addOption(
+				'customId',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks for one custom ID'
+			)
+			->addOption(
+				'status',
+				's',
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks that have a specific status (STATUS_UNKNOWN=0, STATUS_SCHEDULED=1, STATUS_RUNNING=2, STATUS_SUCCESSFUL=3, STATUS_FAILED=4, STATUS_CANCELLED=5)'
+			)
+			->addOption(
+				'scheduledAfter',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks that were scheduled after a specific date (Unix timestamp)'
+			)
+			->addOption(
+				'endedBefore',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks that ended before a specific date (Unix timestamp)'
+			);
+		parent::configure();
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$userIdFilter = $input->getOption('userIdFilter');
+		if ($userIdFilter === null) {
+			$userIdFilter = '';
+		} elseif ($userIdFilter === '') {
+			$userIdFilter = null;
+		}
+		$type = $input->getOption('type');
+		$customId = $input->getOption('customId');
+		$status = $input->getOption('status');
+		$scheduledAfter = $input->getOption('scheduledAfter');
+		$endedBefore = $input->getOption('endedBefore');
+
+		$tasks = $this->taskProcessingManager->getTasks($userIdFilter, $type, $customId, $status, $scheduledAfter, $endedBefore);
+		$arrayTasks = array_map(fn (Task $task): array => $task->jsonSerialize(), $tasks);
+
+		$this->writeArrayInOutputFormat($input, $output, $arrayTasks);
+		return 0;
+	}
+}

core/Command/TaskProcessing/Statistics.php

@@ -0,0 +1,145 @@
+<?php
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OC\Core\Command\TaskProcessing;
+
+use OC\Core\Command\Base;
+use OCP\TaskProcessing\IManager;
+use OCP\TaskProcessing\Task;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class Statistics extends Base {
+	public function __construct(
+		protected IManager $taskProcessingManager,
+	) {
+		parent::__construct();
+	}
+
+	protected function configure() {
+		$this
+			->setName('taskprocessing:task:stats')
+			->setDescription('get statistics for tasks')
+			->addOption(
+				'userIdFilter',
+				'u',
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks for one user ID'
+			)
+			->addOption(
+				'type',
+				't',
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks for one task type'
+			)
+			->addOption(
+				'customId',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks for one custom ID'
+			)
+			->addOption(
+				'status',
+				's',
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks that have a specific status (STATUS_UNKNOWN=0, STATUS_SCHEDULED=1, STATUS_RUNNING=2, STATUS_SUCCESSFUL=3, STATUS_FAILED=4, STATUS_CANCELLED=5)'
+			)
+			->addOption(
+				'scheduledAfter',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks that were scheduled after a specific date (Unix timestamp)'
+			)
+			->addOption(
+				'endedBefore',
+				null,
+				InputOption::VALUE_OPTIONAL,
+				'only get the tasks that ended before a specific date (Unix timestamp)'
+			);
+		parent::configure();
+	}
+
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$userIdFilter = $input->getOption('userIdFilter');
+		if ($userIdFilter === null) {
+			$userIdFilter = '';
+		} elseif ($userIdFilter === '') {
+			$userIdFilter = null;
+		}
+		$type = $input->getOption('type');
+		$customId = $input->getOption('customId');
+		$status = $input->getOption('status');
+		$scheduledAfter = $input->getOption('scheduledAfter');
+		$endedBefore = $input->getOption('endedBefore');
+
+		$tasks = $this->taskProcessingManager->getTasks($userIdFilter, $type, $customId, $status, $scheduledAfter, $endedBefore);
+
+		$stats = ['Number of tasks' => count($tasks)];
+
+		$maxRunningTime = 0;
+		$totalRunningTime = 0;
+		$runningTimeCount = 0;
+
+		$maxQueuingTime = 0;
+		$totalQueuingTime = 0;
+		$queuingTimeCount = 0;
+
+		$maxUserWaitingTime = 0;
+		$totalUserWaitingTime = 0;
+		$userWaitingTimeCount = 0;
+		foreach ($tasks as $task) {
+			// running time
+			if ($task->getStartedAt() !== null && $task->getEndedAt() !== null) {
+				$taskRunningTime = $task->getEndedAt() - $task->getStartedAt();
+				$totalRunningTime += $taskRunningTime;
+				$runningTimeCount++;
+				if ($taskRunningTime >= $maxRunningTime) {
+					$maxRunningTime = $taskRunningTime;
+				}
+			}
+			// queuing time
+			if ($task->getScheduledAt() !== null && $task->getStartedAt() !== null) {
+				$taskQueuingTime = $task->getStartedAt() - $task->getScheduledAt();
+				$totalQueuingTime += $taskQueuingTime;
+				$queuingTimeCount++;
+				if ($taskQueuingTime >= $maxQueuingTime) {
+					$maxQueuingTime = $taskQueuingTime;
+				}
+			}
+			// user waiting time
+			if ($task->getScheduledAt() !== null && $task->getEndedAt() !== null) {
+				$taskUserWaitingTime = $task->getEndedAt() - $task->getScheduledAt();
+				$totalUserWaitingTime += $taskUserWaitingTime;
+				$userWaitingTimeCount++;
+				if ($taskUserWaitingTime >= $maxUserWaitingTime) {
+					$maxUserWaitingTime = $taskUserWaitingTime;
+				}
+			}
+		}
+
+		if ($runningTimeCount > 0) {
+			$stats['Max running time'] = $maxRunningTime;
+			$averageRunningTime = (int)($totalRunningTime / $runningTimeCount);
+			$stats['Average running time'] = $averageRunningTime;
+			$stats['Running time count'] = $runningTimeCount;
+		}
+		if ($queuingTimeCount > 0) {
+			$stats['Max queuing time'] = $maxQueuingTime;
+			$averageQueuingTime = (int)($totalQueuingTime / $queuingTimeCount);
+			$stats['Average queuing time'] = $averageQueuingTime;
+			$stats['Queuing time count'] = $queuingTimeCount;
+		}
+		if ($userWaitingTimeCount > 0) {
+			$stats['Max user waiting time'] = $maxUserWaitingTime;
+			$averageUserWaitingTime = (int)($totalUserWaitingTime / $userWaitingTimeCount);
+			$stats['Average user waiting time'] = $averageUserWaitingTime;
+			$stats['User waiting time count'] = $userWaitingTimeCount;
+		}
+
+		$this->writeArrayInOutputFormat($input, $output, $stats);
+		return 0;
+	}
+}

core/Migrations/Version30000Date20240708160048.php

@@ -34,17 +34,17 @@ public function changeSchema(IOutput $output, Closure $schemaClosure, array $opt
 
 			$table->addColumn('scheduled_at', Types::INTEGER, [
 				'notnull' => false,
-				'default' => 0,
+				'default' => null,
 				'unsigned' => true,
 			]);
 			$table->addColumn('started_at', Types::INTEGER, [
 				'notnull' => false,
-				'default' => 0,
+				'default' => null,
 				'unsigned' => true,
 			]);
 			$table->addColumn('ended_at', Types::INTEGER, [
 				'notnull' => false,
-				'default' => 0,
+				'default' => null,
 				'unsigned' => true,
 			]);
 

core/register_command.php

@@ -140,6 +140,9 @@
 	$application->add(Server::get(Command\Security\BruteforceResetAttempts::class));
 	$application->add(Server::get(Command\SetupChecks::class));
 	$application->add(Server::get(Command\FilesMetadata\Get::class));
+
+	$application->add(Server::get(Command\TaskProcessing\ListCommand::class));
+	$application->add(Server::get(Command\TaskProcessing\Statistics::class));
 } else {
 	$application->add(Server::get(Command\Maintenance\Install::class));
 }

lib/private/TaskProcessing/Db/Task.php

@@ -61,12 +61,12 @@ class Task extends Entity {
 	/**
 	 * @var string[]
 	 */
-	public static array $columns = ['id', 'last_updated', 'type', 'input', 'output', 'status', 'user_id', 'app_id', 'custom_id', 'completion_expected_at', 'error_message', 'progress'];
+	public static array $columns = ['id', 'last_updated', 'type', 'input', 'output', 'status', 'user_id', 'app_id', 'custom_id', 'completion_expected_at', 'error_message', 'progress', 'scheduled_at', 'started_at', 'ended_at'];
 
 	/**
 	 * @var string[]
 	 */
-	public static array $fields = ['id', 'lastUpdated', 'type', 'input', 'output', 'status', 'userId', 'appId', 'customId', 'completionExpectedAt', 'errorMessage', 'progress'];
+	public static array $fields = ['id', 'lastUpdated', 'type', 'input', 'output', 'status', 'userId', 'appId', 'customId', 'completionExpectedAt', 'errorMessage', 'progress', 'scheduledAt', 'startedAt', 'endedAt'];
 
 
 	public function __construct() {
@@ -83,7 +83,7 @@ public function __construct() {
 		$this->addType('completionExpectedAt', 'datetime');
 		$this->addType('errorMessage', 'string');
 		$this->addType('progress', 'float');
-		$this->addType('scheduleAt', 'integer');
+		$this->addType('scheduledAt', 'integer');
 		$this->addType('startedAt', 'integer');
 		$this->addType('endedAt', 'integer');
 	}

lib/private/TaskProcessing/Db/TaskMapper.php

@@ -136,6 +136,35 @@ public function findUserTasksByApp(?string $userId, string $appId, ?string $cust
 		return array_values($this->findEntities($qb));
 	}
 
+	public function findTasks(?string $userId, ?string $taskType = null, ?string $customId = null, ?int $status = null, ?int $scheduleAfter = null, ?int $endedBefore = null): array {
+		$qb = $this->db->getQueryBuilder();
+		$qb->select(Task::$columns)
+			->from($this->tableName);
+
+		// empty string: no userId filter
+		if ($userId !== '') {
+			$qb->where($qb->expr()->eq('user_id', $qb->createPositionalParameter($userId)));
+		}
+		if ($taskType !== null) {
+			$qb->andWhere($qb->expr()->eq('type', $qb->createPositionalParameter($taskType)));
+		}
+		if ($customId !== null) {
+			$qb->andWhere($qb->expr()->eq('custom_id', $qb->createPositionalParameter($customId)));
+		}
+		if ($status !== null) {
+			$qb->andWhere($qb->expr()->eq('status', $qb->createPositionalParameter($status, IQueryBuilder::PARAM_INT)));
+		}
+		if ($scheduleAfter !== null) {
+			$qb->andWhere($qb->expr()->isNotNull('scheduled_at'));
+			$qb->andWhere($qb->expr()->gt('scheduled_at', $qb->createPositionalParameter($scheduleAfter, IQueryBuilder::PARAM_INT)));
+		}
+		if ($endedBefore !== null) {
+			$qb->andWhere($qb->expr()->isNotNull('ended_at'));
+			$qb->andWhere($qb->expr()->lt('ended_at', $qb->createPositionalParameter($endedBefore, IQueryBuilder::PARAM_INT)));
+		}
+		return array_values($this->findEntities($qb));
+	}
+
 	/**
 	 * @param int $timeout
 	 * @return int the number of deleted tasks

lib/private/TaskProcessing/Manager.php

@@ -802,6 +802,19 @@ public function getUserTasks(?string $userId, ?string $taskTypeId = null, ?strin
 		}
 	}
 
+	public function getTasks(
+		?string $userId, ?string $taskTypeId = null, ?string $customId = null, ?int $status = null, ?int $scheduleAfter = null, ?int $endedBefore = null
+	): array {
+		try {
+			$taskEntities = $this->taskMapper->findTasks($userId, $taskTypeId, $customId, $status, $scheduleAfter, $endedBefore);
+			return array_map(fn ($taskEntity): Task => $taskEntity->toPublicTask(), $taskEntities);
+		} catch (\OCP\DB\Exception $e) {
+			throw new \OCP\TaskProcessing\Exception\Exception('There was a problem finding the tasks', 0, $e);
+		} catch (\JsonException $e) {
+			throw new \OCP\TaskProcessing\Exception\Exception('There was a problem parsing JSON after finding the tasks', 0, $e);
+		}
+	}
+
 	public function getUserTasksByApp(?string $userId, string $appId, ?string $customId = null): array {
 		try {
 			$taskEntities = $this->taskMapper->findUserTasksByApp($userId, $appId, $customId);

lib/public/TaskProcessing/IManager.php

@@ -139,6 +139,22 @@ public function getUserTask(int $id, ?string $userId): Task;
 	 */
 	public function getUserTasks(?string $userId, ?string $taskTypeId = null, ?string $customId = null): array;
 
+	/**
+	 * @param string|null $userId The user id that scheduled the task
+	 * @param string|null $taskTypeId The task type id to filter by
+	 * @param string|null $customId
+	 * @param int|null $status The task status
+	 * @param int|null $scheduleAfter Minimum schedule time filter
+	 * @param int|null $endedBefore Maximum ending time filter
+	 * @return list<Task>
+	 * @throws Exception If the query failed
+	 * @throws NotFoundException If the task could not be found
+	 * @since 30.0.0
+	 */
+	public function getTasks(
+		?string $userId, ?string $taskTypeId = null, ?string $customId = null, ?int $status = null, ?int $scheduleAfter = null, ?int $endedBefore = null
+	): array;
+
 	/**
 	 * @param string|null $userId
 	 * @param string $appId