From 7a508d0af6c8d742316951cc0c90dab559e7a6b9 Mon Sep 17 00:00:00 2001 From: Stephen Kuenzli Date: Sun, 24 Dec 2017 16:44:58 -0700 Subject: [PATCH 1/4] Document how and why to configure the `mode` and `max-buffer-size` log options. Documentation based on: * implementation and comments of the [Ring Logger](https://github.com/moby/moby/blob/master/daemon/logger/ring.go#L49) * conversation in implementing [PR 28762](https://github.com/moby/moby/pull/28762) --- engine/admin/logging/overview.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/engine/admin/logging/overview.md b/engine/admin/logging/overview.md index 022c862d6701..b806cfd30e9f 100644 --- a/engine/admin/logging/overview.md +++ b/engine/admin/logging/overview.md @@ -89,6 +89,26 @@ json-file {% endraw %} ``` +## Configure the delivery mode of log messages from container to log driver + +Docker provides two modes for delivering messages from the container to the log driver since Docker 17.04: +1. (default) direct, blocking delivery from container to driver +2. non-blocking delivery that stores log messages in an intermediate per-container ring buffer + +The non-blocking mode of message delivery is useful for ensuring that applications will not block when the logging sub-system is unable to keep up with message throughput. + +*WARNING*: the oldest messages in memory *will be dropped* when the buffer is full, but this is often preferable to blocking the log-writing process of an application. + +The `mode` log option controls whether to use the `blocking` (default) or `non-blocking` message delivery. + +When `mode` is set to `non-blocking`, the `max-buffer-size` log option may be used to control the size of the ring buffer used for intermediate message storage. `max-buffer-size` defaults to 1 megabyte. + +The following example starts an Alpine container with log output in non-blocking mode and a 4 megabyte buffer: + +```bash +$ docker run --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine sh +``` + ### Use environment variables or labels with logging drivers Some logging drivers add the value of a container's `--env|-e` or `--label` From b8bb32f2308b6b0cd1b18978c0bcac4f4f1a486b Mon Sep 17 00:00:00 2001 From: Stephen Kuenzli Date: Tue, 26 Dec 2017 16:50:32 -0700 Subject: [PATCH 2/4] Use a more active voice and adjust formatting per recommendations. --- engine/admin/logging/overview.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/engine/admin/logging/overview.md b/engine/admin/logging/overview.md index b806cfd30e9f..ebe309547ff9 100644 --- a/engine/admin/logging/overview.md +++ b/engine/admin/logging/overview.md @@ -92,16 +92,18 @@ json-file ## Configure the delivery mode of log messages from container to log driver Docker provides two modes for delivering messages from the container to the log driver since Docker 17.04: -1. (default) direct, blocking delivery from container to driver -2. non-blocking delivery that stores log messages in an intermediate per-container ring buffer -The non-blocking mode of message delivery is useful for ensuring that applications will not block when the logging sub-system is unable to keep up with message throughput. +* (default) direct, blocking delivery from container to driver +* non-blocking delivery that stores log messages in an intermediate per-container ring buffer for consumption by driver -*WARNING*: the oldest messages in memory *will be dropped* when the buffer is full, but this is often preferable to blocking the log-writing process of an application. +The `non-blocking` message delivery mode prevents applications from blocking due to logging back pressure. Applications will likely fail in unexpected ways when STDERR or STDOUT streams block. + +> **WARNING**: When the buffer is full and a new message is enqueued, the oldest message in memory is dropped. Dropping messages is often preferred to blocking the log-writing process of an application. +{: .warning} The `mode` log option controls whether to use the `blocking` (default) or `non-blocking` message delivery. -When `mode` is set to `non-blocking`, the `max-buffer-size` log option may be used to control the size of the ring buffer used for intermediate message storage. `max-buffer-size` defaults to 1 megabyte. +The `max-buffer-size` log option controls the size of the ring buffer used for intermediate message storage when `mode` is set to `non-blocking`. `max-buffer-size` defaults to 1 megabyte. The following example starts an Alpine container with log output in non-blocking mode and a 4 megabyte buffer: From e1984707d0a0cbcb45951330d7fac04210a106b5 Mon Sep 17 00:00:00 2001 From: Stephen Kuenzli Date: Tue, 26 Dec 2017 17:24:55 -0700 Subject: [PATCH 3/4] Use a more interesting example for non-blocking mode that will run forever. --- engine/admin/logging/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/admin/logging/overview.md b/engine/admin/logging/overview.md index ebe309547ff9..43874411f94d 100644 --- a/engine/admin/logging/overview.md +++ b/engine/admin/logging/overview.md @@ -108,7 +108,7 @@ The `max-buffer-size` log option controls the size of the ring buffer used for i The following example starts an Alpine container with log output in non-blocking mode and a 4 megabyte buffer: ```bash -$ docker run --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine sh +$ docker run -it --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine ping 127.0.0.1 ``` ### Use environment variables or labels with logging drivers From 5e40b08cfcb3b795114ab4559986a7202b73062a Mon Sep 17 00:00:00 2001 From: Stephen Kuenzli Date: Wed, 27 Dec 2017 14:29:39 -0700 Subject: [PATCH 4/4] Remove reference to an unsupported Docker release. --- engine/admin/logging/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engine/admin/logging/overview.md b/engine/admin/logging/overview.md index 43874411f94d..106f3198d28b 100644 --- a/engine/admin/logging/overview.md +++ b/engine/admin/logging/overview.md @@ -91,7 +91,7 @@ json-file ## Configure the delivery mode of log messages from container to log driver -Docker provides two modes for delivering messages from the container to the log driver since Docker 17.04: +Docker provides two modes for delivering messages from the container to the log driver: * (default) direct, blocking delivery from container to driver * non-blocking delivery that stores log messages in an intermediate per-container ring buffer for consumption by driver