Merge pull request #53001 from nextcloud/feat/setupcheck-task-pickup-speed

feat(SetupChecks): Add check for TaskProcessing pickup speed

Author: marcelklehr

apps/settings/composer/composer/autoload_classmap.php

@@ -129,6 +129,7 @@
     'OCA\\Settings\\SetupChecks\\SecurityHeaders' => $baseDir . '/../lib/SetupChecks/SecurityHeaders.php',
     'OCA\\Settings\\SetupChecks\\SupportedDatabase' => $baseDir . '/../lib/SetupChecks/SupportedDatabase.php',
     'OCA\\Settings\\SetupChecks\\SystemIs64bit' => $baseDir . '/../lib/SetupChecks/SystemIs64bit.php',
+    'OCA\\Settings\\SetupChecks\\TaskProcessingPickupSpeed' => $baseDir . '/../lib/SetupChecks/TaskProcessingPickupSpeed.php',
     'OCA\\Settings\\SetupChecks\\TempSpaceAvailable' => $baseDir . '/../lib/SetupChecks/TempSpaceAvailable.php',
     'OCA\\Settings\\SetupChecks\\TransactionIsolation' => $baseDir . '/../lib/SetupChecks/TransactionIsolation.php',
     'OCA\\Settings\\SetupChecks\\WellKnownUrls' => $baseDir . '/../lib/SetupChecks/WellKnownUrls.php',

apps/settings/composer/composer/autoload_static.php

@@ -144,6 +144,7 @@ class ComposerStaticInitSettings
         'OCA\\Settings\\SetupChecks\\SecurityHeaders' => __DIR__ . '/..' . '/../lib/SetupChecks/SecurityHeaders.php',
         'OCA\\Settings\\SetupChecks\\SupportedDatabase' => __DIR__ . '/..' . '/../lib/SetupChecks/SupportedDatabase.php',
         'OCA\\Settings\\SetupChecks\\SystemIs64bit' => __DIR__ . '/..' . '/../lib/SetupChecks/SystemIs64bit.php',
+        'OCA\\Settings\\SetupChecks\\TaskProcessingPickupSpeed' => __DIR__ . '/..' . '/../lib/SetupChecks/TaskProcessingPickupSpeed.php',
         'OCA\\Settings\\SetupChecks\\TempSpaceAvailable' => __DIR__ . '/..' . '/../lib/SetupChecks/TempSpaceAvailable.php',
         'OCA\\Settings\\SetupChecks\\TransactionIsolation' => __DIR__ . '/..' . '/../lib/SetupChecks/TransactionIsolation.php',
         'OCA\\Settings\\SetupChecks\\WellKnownUrls' => __DIR__ . '/..' . '/../lib/SetupChecks/WellKnownUrls.php',

apps/settings/lib/AppInfo/Application.php

@@ -70,6 +70,7 @@
 use OCA\Settings\SetupChecks\SecurityHeaders;
 use OCA\Settings\SetupChecks\SupportedDatabase;
 use OCA\Settings\SetupChecks\SystemIs64bit;
+use OCA\Settings\SetupChecks\TaskProcessingPickupSpeed;
 use OCA\Settings\SetupChecks\TempSpaceAvailable;
 use OCA\Settings\SetupChecks\TransactionIsolation;
 use OCA\Settings\SetupChecks\WellKnownUrls;
@@ -206,6 +207,7 @@ public function register(IRegistrationContext $context): void {
 		$context->registerSetupCheck(SchedulingTableSize::class);
 		$context->registerSetupCheck(SupportedDatabase::class);
 		$context->registerSetupCheck(SystemIs64bit::class);
+		$context->registerSetupCheck(TaskProcessingPickupSpeed::class);
 		$context->registerSetupCheck(TempSpaceAvailable::class);
 		$context->registerSetupCheck(TransactionIsolation::class);
 		$context->registerSetupCheck(PushService::class);

apps/settings/lib/SetupChecks/TaskProcessingPickupSpeed.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Settings\SetupChecks;
+
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\IL10N;
+use OCP\SetupCheck\ISetupCheck;
+use OCP\SetupCheck\SetupResult;
+use OCP\TaskProcessing\IManager;
+
+class TaskProcessingPickupSpeed implements ISetupCheck {
+	public const MAX_SLOW_PERCENTAGE = 0.2;
+	public const TIME_SPAN = 24;
+
+	public function __construct(
+		private IL10N $l10n,
+		private IManager $taskProcessingManager,
+		private ITimeFactory $timeFactory,
+	) {
+	}
+
+	public function getCategory(): string {
+		return 'ai';
+	}
+
+	public function getName(): string {
+		return $this->l10n->t('Task Processing pickup speed');
+	}
+
+	public function run(): SetupResult {
+		$tasks = $this->taskProcessingManager->getTasks(userId: '', scheduleAfter: $this->timeFactory->now()->getTimestamp() - 60 * 60 * self::TIME_SPAN); // userId: '' means no filter, whereas null would mean guest
+		$taskCount = count($tasks);
+		if ($taskCount === 0) {
+			return SetupResult::success($this->l10n->t('No scheduled tasks in the last {hours} hours.', ['hours' => self::TIME_SPAN]));
+		}
+		$slowCount = 0;
+		foreach ($tasks as $task) {
+			if ($task->getStartedAt() === null) {
+				continue; // task was not picked up yet
+			}
+			if ($task->getScheduledAt() === null) {
+				continue; // task was not scheduled yet -- should not happen, but the API specifies null as return value
+			}
+			$pickupDelay = $task->getScheduledAt() - $task->getStartedAt();
+			if ($pickupDelay > 60 * 4) {
+				$slowCount++; // task pickup took longer than 4 minutes
+			}
+		}
+
+		if ($slowCount / $taskCount < self::MAX_SLOW_PERCENTAGE) {
+			return SetupResult::success($this->l10n->t('Task pickup speed is ok in the last {hours} hours.', ['hours' => self::TIME_SPAN]));
+		} else {
+			return SetupResult::warning($this->l10n->t('Task pickup speed is slow in the last {hours} hours. Many tasks took longer than 4 min to get picked up. Consider setting up a worker to process tasks in the background.', ['hours' => self::TIME_SPAN]), 'https://docs.nextcloud.com/server/latest/admin_manual/ai/overview.html#improve-ai-task-pickup-speed');
+		}
+	}
+}

apps/settings/tests/SetupChecks/TaskProcessingPickupSpeedTest.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCA\Settings\Tests;
+
+use OCA\Settings\SetupChecks\TaskProcessingPickupSpeed;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\IL10N;
+use OCP\SetupCheck\SetupResult;
+use OCP\TaskProcessing\IManager;
+use OCP\TaskProcessing\Task;
+use Test\TestCase;
+
+class TaskProcessingPickupSpeedTest extends TestCase {
+	private IL10N $l10n;
+	private ITimeFactory $timeFactory;
+	private IManager $taskProcessingManager;
+
+	private TaskProcessingPickupSpeed $check;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->l10n = $this->getMockBuilder(IL10N::class)->getMock();
+		$this->timeFactory = $this->getMockBuilder(ITimeFactory::class)->getMock();
+		$this->taskProcessingManager = $this->getMockBuilder(IManager::class)->getMock();
+
+		$this->check = new TaskProcessingPickupSpeed(
+			$this->l10n,
+			$this->taskProcessingManager,
+			$this->timeFactory,
+		);
+	}
+
+	public function testPass(): void {
+		$tasks = [];
+		for ($i = 0; $i < 100; $i++) {
+			$task = new Task('test', ['test' => 'test'], 'settings', 'user' . $i);
+			$task->setStartedAt(0);
+			if ($i < 15) {
+				$task->setScheduledAt(60 * 5); // 15% get 5mins
+			} else {
+				$task->setScheduledAt(60); // the rest gets 1min
+			}
+			$tasks[] = $task;
+		}
+		$this->taskProcessingManager->method('getTasks')->willReturn($tasks);
+
+		$this->assertEquals(SetupResult::SUCCESS, $this->check->run()->getSeverity());
+	}
+
+	public function testFail(): void {
+		$tasks = [];
+		for ($i = 0; $i < 100; $i++) {
+			$task = new Task('test', ['test' => 'test'], 'settings', 'user' . $i);
+			$task->setStartedAt(0);
+			if ($i < 30) {
+				$task->setScheduledAt(60 * 5); // 30% get 5mins
+			} else {
+				$task->setScheduledAt(60); // the rest gets 1min
+			}
+			$tasks[] = $task;
+		}
+		$this->taskProcessingManager->method('getTasks')->willReturn($tasks);
+
+		$this->assertEquals(SetupResult::WARNING, $this->check->run()->getSeverity());
+	}
+}