Elastic Logging Plugin configuration options

Use the following options to configure the Elastic Logging Plugin for Docker. You can pass these options with the --log-opt flag when you start a container, or you can set them in the daemon.json file for all containers.

Usage examples

edit

To set configuration options when you start a container:

docker run --log-driver=elastic/elastic-logging-plugin:8.16.1 \
           --log-opt hosts="https://myhost:9200" \
           --log-opt user="myusername" \
           --log-opt password="mypassword" \
           -it debian:jessie /bin/bash

To set configuration options for all containers in the daemon.json file:

{
  "log-driver" : "elastic/elastic-logging-plugin:8.16.1",
  "log-opts" : {
    "hosts" : "https://myhost:9200",
    "user" : "myusername",
    "password" : "mypassword"
  }
}

For more examples, see Usage examples.

Elastic Cloud options

edit

Option	Description
`cloud_id`	The Cloud ID found in the Elastic Cloud web console. This ID is used to resolve the Elastic Stack URLs when connecting to Elasticsearch Service on Elastic Cloud.
`cloud_auth`	The username and password combination for connecting to Elasticsearch Service on Elastic Cloud. The format is `"username:password"`.

Elasticsearch output options

edit

Option	Default	Description
`hosts`	`"localhost:9200"`	The list of Elasticsearch nodes to connect to. Specify each node as a `URL` or `IP:PORT`. For example: `http://192.0.2.0`, `https://myhost:9230` or `192.0.2.0:9300`. If no port is specified, the default is `9200`.
`user`		The basic authentication username for connecting to Elasticsearch.
`password`		The basic authentication password for connecting to Elasticsearch.
`index`		A format string value that specifies the index to write events to when you’re using daily indices. For example: `"dockerlogs-%{+yyyy.MM.dd}"`.
Advanced:
`name`	`testbeat`	A custom value that will be inserted into the document as `agent.name`. If not set, it will be the hostname of Docker host.
`backoff_init`	`1s`	The number of seconds to wait before trying to reconnect to Elasticsearch after a network error. After waiting `backoff.init` seconds, the Elastic Logging Plugin tries to reconnect. If the attempt fails, the backoff timer is increased exponentially up to `backoff.max`. After a successful connection, the backoff timer is reset.
`backoff_max`	`60s`	The maximum number of seconds to wait before attempting to connect to Elasticsearch after a network error.
`api_key`		Instead of using usernames and passwords, you can use API keys to secure communication with Elasticsearch.
`pipeline`		A format string value that specifies the Elasticsearch ingest pipeline to write events to.
`timeout`	`90`	The http request timeout in seconds for the Elasticsearch request.
`proxy_url`		The URL of the proxy to use when connecting to the Elasticsearch servers. The value may be either a complete URL or a `host[:port]`, in which case the `http` scheme is assumed. If a value is not specified through the configuration file then proxy environment variables are used. See the Go documentation for more information about the environment variables.

Configuring the local log

edit

This plugin fully supports docker logs, and it maintains a local copy of logs that can be read without a connection to Elasticsearch. The plugin mounts the /var/lib/docker directory on the host to write logs to /var/log/containers on the host. If you want to change the log location on the host, you must change the mount inside the plugin:

Disable the plugin:

docker plugin disable elastic/elastic-logging-plugin:8.16.1

Set the bindmount directory:

docker plugin set elastic/elastic-logging-plugin:8.16.1 LOG_DIR.source=NEW_LOG_LOCATION

Enable the plugin:

docker plugin enable elastic/elastic-logging-plugin:8.16.1

The local log also supports the max-file, max-size and compress options that are a part of the Docker default file logger. For example:

docker run --log-driver=elastic/elastic-logging-plugin:8.16.1 \
           --log-opt hosts="myhost:9200" \
           --log-opt user="myusername" \
           --log-opt password="mypassword" \
           --log-opt max-file=10 \
           --log-opt max-size=5M \
           --log-opt compress=true \
           -it debian:jessie /bin/bash

In situations where logs can’t be easily managed, for example, you can also configure the plugin to remove log files when a container is stopped. This will prevent you from reading logs on a stopped container, but it will rotate logs without user intervention. To enable removal of logs for stopped containers, you must change the DESTROY_LOGS_ON_STOP environment variable:

Disable the plugin:

docker plugin disable elastic/elastic-logging-plugin:8.16.1

Enable log removal:

docker plugin set elastic/elastic-logging-plugin:8.16.1 DESTROY_LOGS_ON_STOP=true

Enable the plugin:

docker plugin enable elastic/elastic-logging-plugin:8.16.1

« Install and configure the Elastic Logging Plugin Elastic Logging Plugin usage examples »