Add latest changes from gitlab-org/gitlab@master

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md
index 2010a21130d..d510414baa3 100644
--- a/doc/development/sidekiq/index.md
+++ b/doc/development/sidekiq/index.md
@@ -114,6 +114,41 @@ def perform(project_id)
 end
 ```
 
+## Deferring Sidekiq workers
+
+Sidekiq workers are deferred by two ways,
+
+1. Manual: Feature flags can be used to explicitly defer a particular worker, more details can be found [here](../feature_flags/index.md#deferring-sidekiq-jobs).
+1. Automatic: Similar to the [throttling mechanism](../database/batched_background_migrations.md#throttling-batched-migrations) in batched migrations, database health indicators are used to defer a Sidekiq worker.
+
+   To use the automatic deferring mechanism, worker has to opt-in by calling `defer_on_database_health_signal` with gitlab_schema, delay_by (time to delay) and tables (which is used by autovacuum db indicator) as it's parameters.
+
+   **Example:**
+
+   ```ruby
+    module Chaos
+      class SleepWorker # rubocop:disable Scalability/IdempotentWorker
+        include ApplicationWorker
+
+        data_consistency :always
+
+        sidekiq_options retry: 3
+        include ChaosQueue
+
+        defer_on_database_health_signal :gitlab_main, 1.minute, [:users]
+
+        def perform(duration_s)
+          Gitlab::Chaos.sleep(duration_s)
+        end
+      end
+    end
+   ```
+
+For deferred jobs, logs contain the following to indicate the source:
+
+- `job_status`: `deferred`
+- `job_deferred_by`: 'feature_flag' or 'database_health_check'
+
 ## Sidekiq Queues
 
 Previously, each worker had its own queue, which was automatically set based on the