diff options
author | Luca Cillario <luca.cillario.95@gmail.com> | 2022-11-21 11:03:19 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-11-21 12:03:19 +0200 |
commit | af44021f3a595637b4ef2c3a873d628b309905a1 (patch) | |
tree | 287c590e356fae56ab986ca763848a73af788f97 | |
parent | fa45fb13730c6ece6b08184b4f475d841895b4d4 (diff) | |
download | redis-py-af44021f3a595637b4ef2c3a873d628b309905a1.tar.gz |
Retry documentation. (#2166) (#2456)
* Retry documentation. (#2166)
* Fixed typo.
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
* Update docs/retry.rst
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
Co-authored-by: Nermina Miller <102551568+nermiller@users.noreply.github.com>
-rw-r--r-- | docs/backoff.rst | 2 | ||||
-rw-r--r-- | docs/exceptions.rst | 2 | ||||
-rw-r--r-- | docs/retry.rst | 67 |
3 files changed, 69 insertions, 2 deletions
diff --git a/docs/backoff.rst b/docs/backoff.rst index e640b56..c5ab01a 100644 --- a/docs/backoff.rst +++ b/docs/backoff.rst @@ -1,3 +1,5 @@ +.. _backoff-label: + Backoff ############# diff --git a/docs/exceptions.rst b/docs/exceptions.rst index b8aeb33..8a9fe45 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -1,4 +1,4 @@ - +.. _exceptions-label: Exceptions ########## diff --git a/docs/retry.rst b/docs/retry.rst index 2b4f22c..acf198e 100644 --- a/docs/retry.rst +++ b/docs/retry.rst @@ -2,4 +2,69 @@ Retry Helpers ############# .. automodule:: redis.retry - :members:
\ No newline at end of file + :members: + + +Retry in Redis Standalone +************************** + +>>> from redis.backoff import ExponentialBackoff +>>> from redis.retry import Retry +>>> from redis.client import Redis +>>> from redis.exceptions import ( +>>> BusyLoadingError, +>>> ConnectionError, +>>> TimeoutError +>>> ) +>>> +>>> # Run 3 retries with exponential backoff strategy +>>> retry = Retry(ExponentialBackoff(), 3) +>>> # Redis client with retries on custom errors +>>> r = Redis(host='localhost', port=6379, retry=retry, retry_on_error=[BusyLoadingError, ConnectionError, TimeoutError]) +>>> # Redis client with retries on TimeoutError only +>>> r_only_timeout = Redis(host='localhost', port=6379, retry=retry, retry_on_timeout=True) + +As you can see from the example above, Redis client supports 3 parameters to configure the retry behaviour: + +* ``retry``: :class:`~.Retry` instance with a :ref:`backoff-label` strategy and the max number of retries +* ``retry_on_error``: list of :ref:`exceptions-label` to retry on +* ``retry_on_timeout``: if ``True``, retry on :class:`~.TimeoutError` only + +If either ``retry_on_error`` or ``retry_on_timeout`` are passed and no ``retry`` is given, +by default it uses a ``Retry(NoBackoff(), 1)`` (meaning 1 retry right after the first failure). + + +Retry in Redis Cluster +************************** + +>>> from redis.backoff import ExponentialBackoff +>>> from redis.retry import Retry +>>> from redis.cluster import RedisCluster +>>> +>>> # Run 3 retries with exponential backoff strategy +>>> retry = Retry(ExponentialBackoff(), 3) +>>> # Redis Cluster client with retries +>>> rc = RedisCluster(host='localhost', port=6379, retry=retry, cluster_error_retry_attempts=2) + +Retry behaviour in Redis Cluster is a little bit different from Standalone: + +* ``retry``: :class:`~.Retry` instance with a :ref:`backoff-label` strategy and the max number of retries, default value is ``Retry(NoBackoff(), 0)`` +* ``cluster_error_retry_attempts``: number of times to retry before raising an error when :class:`~.TimeoutError` or :class:`~.ConnectionError` or :class:`~.ClusterDownError` are encountered, default value is ``3`` + +Let's consider the following example: + +>>> from redis.backoff import ExponentialBackoff +>>> from redis.retry import Retry +>>> from redis.cluster import RedisCluster +>>> +>>> rc = RedisCluster(host='localhost', port=6379, retry=Retry(ExponentialBackoff(), 6), cluster_error_retry_attempts=1) +>>> rc.set('foo', 'bar') + +#. the client library calculates the hash slot for key 'foo'. +#. given the hash slot, it then determines which node to connect to, in order to execute the command. +#. during the connection, a :class:`~.ConnectionError` is raised. +#. because we set ``retry=Retry(ExponentialBackoff(), 6)``, the client tries to reconnect to the node up to 6 times, with an exponential backoff between each attempt. +#. even after 6 retries, the client is still unable to connect. +#. because we set ``cluster_error_retry_attempts=1``, before giving up, the client starts a cluster update, removes the failed node from the startup nodes, and re-initializes the cluster. +#. after the cluster has been re-initialized, it starts a new cycle of retries, up to 6 retries, with an exponential backoff. +#. if the client can connect, we're good. Otherwise, the exception is finally raised to the caller, because we've run out of attempts.
\ No newline at end of file |