Skip to content

Commit c16602d

Browse files
thaJeztahthaJeztah
committed
logging: document dual-logging cache options
While dual-logging is enabled automatically, it is possible to disable this feature, or to configure the default options. This patch adds documentation for these options. Signed-off-by: Sebastiaan van Stijn <[email protected]>
1 parent b6fc755 commit c16602d

2 files changed

Lines changed: 78 additions & 19 deletions

File tree

‎config/containers/logging/dual-logging.md‎

Lines changed: 76 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Learn how to read container logs locally when using a third party logging solution.
3-
keywords: docker, logging, driver
4-
title: Use docker logs to read container logs for remote logging drivers
3+
keywords: docker, logging, driver, dual logging, dual-logging, cache, ring-buffer, configuration
4+
title: Use docker logs with remote logging drivers
55
---
66

77
## Overview
@@ -21,9 +21,16 @@ logs regardless of the configured logging driver or plugin. This capability,
2121
referred to as "dual logging", allows you to use `docker logs` to read container
2222
logs locally in a consistent format, regardless of the log driver used, because
2323
the engine is configured to log information to the “local” logging driver. Refer
24-
to [Configure the default logging driver](/config/containers/logging/configure)
25-
for additional information.
24+
to [Configure the default logging driver](configure.md) for additional information.
2625

26+
Dual logging uses the [`local`](local.md) logging driver to act as cache for
27+
reading the latest logs of your containers. By default, the cache has log-file
28+
rotation enabled, and is limited to a maximum of 5 files of 20MB each (before
29+
compression) per container.
30+
31+
Refer to the [configuration options](#configuration-options) section to customize
32+
these defaults, or to the [disable dual-logging](#disable-the-dual-logging-cache)
33+
section to disable this feature.
2734

2835
## Prerequisites
2936

@@ -34,11 +41,11 @@ support reading logs.
3441
The following examples show the result of running a `docker logs` command with
3542
and without dual logging availability:
3643

37-
### Without dual logging capability:
44+
### Without dual logging capability
3845

39-
When a container or `dockerd` was configured with a remote logging driver such
40-
as `splunk`, an error was displayed when attempting to read container logs
41-
locally:
46+
When a container is configured with a remote logging driver such as `splunk`, and
47+
dual logging is disabled, an error is displayed when attempting to read container
48+
logs locally:
4249

4350
- Step 1: Configure Docker daemon
4451

@@ -47,7 +54,8 @@ locally:
4754
{
4855
"log-driver": "splunk",
4956
"log-opts": {
50-
...
57+
"cache-disabled": "true",
58+
... (options for "splunk" logging driver)
5159
}
5260
}
5361
```
@@ -65,9 +73,12 @@ locally:
6573
Error response from daemon: configured logging driver does not support reading
6674
```
6775

68-
### With dual logging capability:
76+
### With dual logging capability
6977

70-
To configure a container or docker with a remote logging driver such as splunk:
78+
With the dual logging cache enabled, the `docker logs` command can be used to
79+
read logs, even if the logging driver does not support reading logs. The following
80+
examples shows a daemon configuration that uses the `splunk` remote logging driver
81+
as a default, with dual logging caching enabled:
7182

7283
- Step 1: Configure Docker daemon
7384

@@ -76,7 +87,7 @@ To configure a container or docker with a remote logging driver such as splunk:
7687
{
7788
"log-driver": "splunk",
7889
"log-opts": {
79-
...
90+
... (options for "splunk" logging driver)
8091
}
8192
}
8293
```
@@ -102,14 +113,63 @@ To configure a container or docker with a remote logging driver such as splunk:
102113

103114
> **Note**
104115
>
105-
> For a local driver, such as `json-file` and `journald`, there is no difference in
106-
> functionality before or after the dual logging capability became available.
107-
> The log is locally visible in both scenarios.
116+
> For logging drivers that support reading logs, such as the `local`, `json-file`
117+
> and `journald` drivers, there is no difference in functionality before or after
118+
> the dual logging capability became available. For these drivers, Logs can be
119+
> read using `docker logs` in both scenarios.
120+
121+
122+
### Configuration options
123+
124+
The "dual logging" cache accepts the same configuration options as the
125+
[`local` logging driver](local.md), but with a `cache-` prefix. These options
126+
can be specified per container, and defaults for new containers can be set using
127+
the [daemon configuration file](/engine/reference/commandline/dockerd/#daemon-configuration-file).
128+
129+
By default, the cache has log-file rotation enabled, and is limited to a maximum
130+
of 5 files of 20MB each (before compression) per container. Use the configuration
131+
options described below to customize these defaults.
132+
133+
134+
| Option | Default | Description |
135+
|:-----------------|:----------|:--------------------------------------------------------------------------------------------------------------------------------------------------|
136+
| `cache-disabled` | `"false"` | Disable local caching. Boolean value passed as a string (`true`, `1`, `0`, or `false`). |
137+
| `cache-max-size` | `"20m"` | The maximum size of the cache before it is rotated. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). |
138+
| `cache-max-file` | `"5"` | The maximum number of cache files that can be present. If rotating the logs creates excess files, the oldest file is removed. A positive integer. |
139+
| `cache-compress` | `"true"` | Enable or disable compression of rotated log files. Boolean value passed as a string (`true`, `1`, `0`, or `false`). |
108140

141+
## Disable the dual logging cache
142+
143+
Use the `cache-disabled` option to disable the dual logging cache. Disabling the
144+
cache can be useful to save storage space in situations where logs are only read
145+
through a remote logging system, and if there is no need to read logs through
146+
`docker logs` for debugging purposes.
147+
148+
Caching can be disabled for individual containers or by default for new containers,
149+
when using the [daemon configuration file](/engine/reference/commandline/dockerd/#daemon-configuration-file).
150+
151+
The following example uses the daemon configuration file to use the ["splunk'](splunk.md)
152+
logging driver as a default, with caching disabled:
153+
154+
```console
155+
$ cat /etc/docker/daemon.json
156+
{
157+
"log-driver": "splunk",
158+
"log-opts": {
159+
"cache-disabled": "true",
160+
... (options for "splunk" logging driver)
161+
}
162+
}
163+
```
164+
165+
> **Note**
166+
>
167+
> For logging drivers that support reading logs, such as the `local`, `json-file`
168+
> and `journald` drivers, dual logging is not used, and disabling the option has
169+
> no effect.
109170
110171
## Limitations
111172

112-
- You cannot specify more than one log driver.
113173
- If a container using a logging driver or plugin that sends logs remotely
114174
suddenly has a "network" issue, no ‘write’ to the local cache occurs.
115175
- If a write to `logdriver` fails for any reason (file system full, write

‎config/containers/logging/index.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,8 @@ In some cases, `docker logs` may not show useful information unless you take
2626
additional steps.
2727

2828
- If you use a [logging driver](configure.md) which sends logs to a file, an
29-
external host, a database, or another logging back-end, `docker logs` may not
30-
show useful information.
31-
29+
external host, a database, or another logging back-end, and have ["dual logging"](dual-logging.md)
30+
disabled, `docker logs` may not show useful information.
3231
- If your image runs a non-interactive process such as a web server or a
3332
database, that application may send its output to log files instead of `STDOUT`
3433
and `STDERR`.

0 commit comments

Comments
 (0)