Redis docs: Mention visibility timeouts

docs/getting-started/brokers/redis.rst

@@ -39,6 +39,21 @@ Where the URL is in the format of::
 all fields after the scheme are optional, and will default to localhost on port 6379,
 using database 0.
 
+.. _redis-visibility_timeout:
+
+Visibility Timeout
+------------------
+
+The visibility timeout defines the number of seconds to wait
+for the worker to acknowledge the task before the message is redelivered
+to another worker.  Be sure to see :ref:`redis-caveats` below.
+
+This option is set via the :setting:`BROKER_TRANSPORT_OPTIONS` setting::
+
+    BROKER_TRANSPORT_OPTIONS = {'visibility_timeout': 3600}  # 1 hour.
+
+The default visibility timeout for Redis is 1 hour.
+
 .. _redis-results-configuration:
 
 Results
@@ -51,3 +66,34 @@ you should configure these settings::
 
 For a complete list of options supported by the Redis result backend, see
 :ref:`conf-redis-result-backend`
+
+.. _redis-caveats:
+
+Caveats
+=======
+
+- If a task is not acknowledged within the :ref:`redis-visibility_timeout`
+  the task will be redelivered to another worker and executed.
+
+    This causes problems with ETA/countdown/retry tasks where the
+    time to execute exceeds the visibility timeout; in fact if that
+    happens it will be executed again, and again in a loop.
+
+    So you have to increase the visibility timeout to match
+    the time of the longest ETA you are planning to use.
+
+    Note that Celery will redeliver messages at worker shutdown,
+    so having a long visibility timeout will only delay the redelivery
+    of 'lost' tasks in the event of a power failure or forcefully terminated
+    workers.
+
+    Periodic tasks will not be affected by the visibility timeout,
+    as this is a concept separate from ETA/countdown.
+
+    You can increase this timeout by configuring a transport option
+    with the same name:
+
+        BROKER_TRANSPORT_OPTIONS = {'visibility_timeout': 43200}
+
+    The value must be an int describing the number of seconds.
+