Configure logging drivers (original) (raw)

Docker includes multiple logging mechanisms to help you get information from running containers and services. These mechanisms are called logging drivers. Each Docker daemon has a default logging driver, which each container uses unless you configure it to use a different logging driver, or log driver for short.

As a default, Docker uses thejson-file logging driver, which caches container logs as JSON internally. In addition to using the logging drivers included with Docker, you can also implement and uselogging driver plugins.

Tip

Use the local logging driver to prevent disk-exhaustion. By default, no log-rotation is performed. As a result, log-files stored by the defaultjson-file logging driver logging driver can cause a significant amount of disk space to be used for containers that generate much output, which can lead to disk space exhaustion.

Docker keeps the json-file logging driver (without log-rotation) as a default to remain backwards compatible with older versions of Docker, and for situations where Docker is used as runtime for Kubernetes.

For other situations, the local logging driver is recommended as it performs log-rotation by default, and uses a more efficient file format. Refer to theConfigure the default logging driversection below to learn how to configure the local logging driver as a default, and thelocal file logging driver page for more details about thelocal logging driver.

To configure the Docker daemon to default to a specific logging driver, set the value of log-driver to the name of the logging driver in the daemon.jsonconfiguration file. Refer to the "daemon configuration file" section in thedockerd reference manualfor details.

The default logging driver is json-file. The following example sets the default logging driver to thelocal log driver:

If the logging driver has configurable options, you can set them in thedaemon.json file as a JSON object with the key log-opts. The following example sets four configurable options on the json-file logging driver:

Restart Docker for the changes to take effect for newly created containers. Existing containers don't use the new logging configuration automatically.

Note

log-opts configuration options in the daemon.json configuration file must be provided as strings. Boolean and numeric values (such as the value formax-file in the example above) must therefore be enclosed in quotes (").

If you don't specify a logging driver, the default is json-file. To find the current default logging driver for the Docker daemon, rundocker info and search for Logging Driver. You can use the following command on Linux, macOS, or PowerShell on Windows:

Note

Changing the default logging driver or logging driver options in the daemon configuration only affects containers that are created after the configuration is changed. Existing containers retain the logging driver options that were used when they were created. To update the logging driver for a container, the container has to be re-created with the desired options. Refer to theconfigure the logging driver for a containersection below to learn how to find the logging-driver configuration of a container.

When you start a container, you can configure it to use a different logging driver than the Docker daemon's default, using the --log-driver flag. If the logging driver has configurable options, you can set them using one or more instances of the --log-opt <NAME>=<VALUE> flag. Even if the container uses the default logging driver, it can use different configurable options.

The following example starts an Alpine container with the none logging driver.

To find the current logging driver for a running container, if the daemon is using the json-file logging driver, run the following docker inspectcommand, substituting the container name or ID for <CONTAINER>:

Docker provides two modes for delivering messages from the container to the log driver:

The non-blocking message delivery mode prevents applications from blocking due to logging back pressure. Applications are likely to fail in unexpected ways when STDERR or STDOUT streams block.

Warning

When the buffer is full, new messages will not be enqueued. Dropping messages is often preferred to blocking the log-writing process of an application.

The mode log option controls whether to use the blocking (default) ornon-blocking message delivery.

The max-buffer-size controls the size of the buffer used for intermediate message storage when mode is set to non-blocking. The default is 1m meaning 1 MB (1 million bytes). Seefunction FromHumanSize() in the go-units package for the allowed format strings, some examples are 1KiB for 1024 bytes, 2g for 2 billion bytes.

The following example starts an Alpine container with log output in non-blocking mode and a 4 megabyte buffer:

Use environment variables or labels with logging drivers

Some logging drivers add the value of a container's --env|-e or --labelflags to the container's logs. This example starts a container using the Docker daemon's default logging driver (in the following example, json-file) but sets the environment variable os=ubuntu.

If the logging driver supports it, this adds additional fields to the logging output. The following output is generated by the json-file logging driver:

The following logging drivers are supported. See the link to each driver's documentation for its configurable options, if applicable. If you are usinglogging driver plugins, you may see more options.

Driver Description
none No logs are available for the container and docker logs does not return any output.
local Logs are stored in a custom format designed for minimal overhead.
json-file The logs are formatted as JSON. The default logging driver for Docker.
syslog Writes logging messages to the syslog facility. The syslog daemon must be running on the host machine.
journald Writes log messages to journald. The journald daemon must be running on the host machine.
gelf Writes log messages to a Graylog Extended Log Format (GELF) endpoint such as Graylog or Logstash.
fluentd Writes log messages to fluentd (forward input). The fluentd daemon must be running on the host machine.
awslogs Writes log messages to Amazon CloudWatch Logs.
splunk Writes log messages to splunk using the HTTP Event Collector.
etwlogs Writes log messages as Event Tracing for Windows (ETW) events. Only available on Windows platforms.
gcplogs Writes log messages to Google Cloud Platform (GCP) Logging.