Skip to content

Document the mode and max-buffer-size log options #5613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mdlinville merged 4 commits into from
Dec 27, 2017
Merged

Document the mode and max-buffer-size log options #5613

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7a508d0
Document how and why to configure the `mode` and `max-buffer-size` lo…
skuenzli Dec 24, 2017
b8bb32f
Use a more active voice and adjust formatting per recommendations.
skuenzli Dec 26, 2017
e198470
Use a more interesting example for non-blocking mode that will run fo…
skuenzli Dec 27, 2017
5e40b08
Remove reference to an unsupported Docker release.
skuenzli Dec 27, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions engine/admin/logging/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,28 @@ 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:

* (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

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.

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:

```bash
$ 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

Some logging drivers add the value of a container's `--env|-e` or `--label`
Expand Down