Merge pull request #8087 from nextcloud/feature/noid/background-job-maintenance-window

Background job maintenance window

admin_manual/configuration_server/background_jobs_configuration.rst

@@ -19,12 +19,17 @@ externally mounted file systems.
 
 Parameters
 ----------
-In the admin settings menu you can configure how cron-jobs should be executed.
-You can choose between the following options:
 
--   AJAX
--   Webcron
--   Cron
+``maintenance_window_start``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the ``config/config.php`` file you can specify this config.
+Some background jobs only run once a day. When an hour is defined (timezone is UTC)
+for this config, the background jobs which advertise themselves as not time sensitive
+will be delayed during the "working" hours and only run in the 4 hours after the given
+time. This is e.g. used for activity expiration, suspicious login training and update checks.
+
+A value of 1 e.g. will only run these background jobs between 01:00am UTC and 05:00am UTC.
 
 Cron jobs
 ---------
@@ -115,7 +120,7 @@ This approach requires two files: **nextcloudcron.service** and **nextcloudcron.
 
 Replace the user ``www-data`` with the user of your http server and ``/var/www/nextcloud/cron.php`` with the location of **cron.php** in your nextcloud directory.
 
-The ``KillMode=process`` setting is necessary for external programs that are started by the cron job to keep running after the cron job has finished. 
+The ``KillMode=process`` setting is necessary for external programs that are started by the cron job to keep running after the cron job has finished.
 
 Note that the **.service** unit file does not need an ``[Install]`` section. Please check your setup because we recommended it in earlier versions of this admin manual.
 

developer_manual/basics/backgroundjobs.rst

@@ -43,7 +43,7 @@ your job class of choice.
             $this->myService = $service;
 
             // Run once an hour
-            parent::setInterval(3600);
+            $this->setInterval(3600);
         }
 
         protected function run($arguments) {
@@ -62,6 +62,25 @@ to pass on to the service to run the background job.
 The ``run`` function is the main thing you need to implement and where all the
 logic happens.
 
+Heavy load and time insensitive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the background job is a ``\OCP\BackgroundJob\TimedJob`` and can impact the performance of
+the instance and is not time sensitive, e.g. clearing old data, running training of AI models
+or similar things, consider flagging it as time insensitive in the constructor.
+
+.. code-block:: php
+
+    <?php
+
+    // Run once a day
+    $this->setInterval(24 * 3600);
+    // Delay until low-load time
+    $this->setTimeSensitivity(\OCP\BackgroundJob\IJob::TIME_INSENSITIVE);
+
+This allows the Nextcloud to delay the job until a given nightly time window so the users
+are not that impacted by the heavy load of the background job.
+
 Registering a background job
 ----------------------------
 
@@ -77,7 +96,7 @@ You can register your jobs in your info.xml by addning;
 .. code-block:: xml
 
     <background-jobs>
-		  <job>OCA\MyApp\Cron\SomeTask</job>
+        <job>OCA\MyApp\Cron\SomeTask</job>
     </background-jobs>
 
 This will on install/update of the application add the job ``OCA\MyApp\Cron\SomeTask``.