diff --git a/README.rst b/README.rst index 6e9bfaa..0d62a4b 100644 --- a/README.rst +++ b/README.rst @@ -269,6 +269,34 @@ botocore debug logs to print to stderr but not to Cloudwatch: logger = logging.getLogger() logger.addHandler(watchtower.CloudWatchLogHandler()) +Resiliency to network outages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +On startup, watchtower queries the configured log group, and creates it if it does not exist. A failure +to query or create the log group for any reason will cause watchtower to crash and prevent your application from starting. +This is intended, since otherwise watchtower cannot deliver your logs. If you +require your application to be able to start even during a network connectivity outage or a CloudWatch Logs service outage, +consider setting the ``create_log_group`` parameter to ``False`` in the handler configuration. With this in place, +watchtower is able to start completely offline. If the configuration is otherwise correct, watchtower will resume sending +logs when it regains a connection to the service. + +When your logs are ready to be sent, watchtower uses the following +`boto3 retry configuration `_: + +- Standard retry mode +- 8 retry attempts with exponential backoff + +This means watchtower will attempt to send your log batch 8 times over the course of FIXME seconds. If all attempts fail, +watchotwer will give up and print a warning to stderr that the log batch was lost. If you want to use a custom configuration +(for example, to increase the number of retries), you can supply one to the handler as shown in the following example: + +.. code-block:: python + + import boto3 + from botocore.config import Config + client_config = Config(connect_timeout=5, read_timeout=60, retries={"max_attempts": 20, "mode": "standard"}) + logs_client = boto3.client("logs", config=client_config) + watchtower.CloudWatchLogHandler(boto3_client=logs_client) + Authors ~~~~~~~ * Andrey Kislyuk