From cd426ebed79e29153eb29ea1ccb260e15db2fea5 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Tue, 13 Oct 2015 08:39:47 +0200 Subject: [PATCH] Add docs for label/env log-opts Signed-off-by: Vincent Demeester --- docs/reference/logging/fluentd.md | 18 +++++++++++++++ docs/reference/logging/journald.md | 25 +++++++++++++++++++++ docs/reference/logging/overview.md | 35 ++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+) diff --git a/docs/reference/logging/fluentd.md b/docs/reference/logging/fluentd.md index 12ea2ab387..91b35a9062 100644 --- a/docs/reference/logging/fluentd.md +++ b/docs/reference/logging/fluentd.md @@ -73,6 +73,24 @@ Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. +### labels and env + +The `labels` and `env` options takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence. + +To use attributes, specify them when you start the Docker daemon. + +``` +docker daemon --log-driver=fluentd --log-opt labels=foo --log-opt env=foo,fizz +``` + +Then, run a container and specify values for the `labels` or `env`. For example, you might use this: + +``` +docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py +```` + +This adds additional fields to the extra attributes of a logging message. + ## Fluentd daemon management with Docker About `Fluentd` itself, see [the project webpage](http://www.fluentd.org) diff --git a/docs/reference/logging/journald.md b/docs/reference/logging/journald.md index cd7358bd0f..5d3d1c9153 100644 --- a/docs/reference/logging/journald.md +++ b/docs/reference/logging/journald.md @@ -36,6 +36,31 @@ You can set the logging driver for a specific container by using the docker run --log-driver=journald ... +## Options + +Users can use the `--log-opt NAME=VALUE` flag to specify additional +journald logging driver options. + +### labels and env + +The `labels` and `env` options takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence. + +To use attributes, specify them when you start the Docker daemon. + +``` +docker daemon --log-driver=journald --log-opt labels=foo --log-opt env=foo,fizz +``` + +Then, run a container and specify values for the `labels` or `env`. For example, you might use this: + +``` +docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py +```` + +This adds additional metadata in the journal with each message, one +for each key that matches. + + ## Note regarding container names The value logged in the `CONTAINER_NAME` field is the container name diff --git a/docs/reference/logging/overview.md b/docs/reference/logging/overview.md index 9911a77133..f76f7b7f8c 100644 --- a/docs/reference/logging/overview.md +++ b/docs/reference/logging/overview.md @@ -27,12 +27,15 @@ container's logging driver. The following options are supported: The `docker logs`command is available only for the `json-file` logging driver. + ## json-file options The following logging options are supported for the `json-file` logging driver: --log-opt max-size=[0-9+][k|m|g] --log-opt max-file=[0-9+] + --log-opt labels=label1,label2 + --log-opt env=env1,env2 Logs that reach `max-size` are rolled over. You can set the size in kilobytes(k), megabytes(m), or gigabytes(g). eg `--log-opt max-size=50m`. If `max-size` is not set, then logs are not rolled over. @@ -41,6 +44,26 @@ Logs that reach `max-size` are rolled over. You can set the size in kilobytes(k) If `max-size` and `max-file` are set, `docker logs` only returns the log lines from the newest log file. +The `labels` and `env` options add additional attributes for use with logging drivers that accept them. Each of these options takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence. + +To use attributes, specify them when you start the Docker daemon. + +``` +docker daemon --log-driver=json-file --log-opt labels=foo --log-opt env=foo,fizz +``` + +Then, run a container and specify values for the `labels` or `env`. For example, you might use this: + +``` +docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py +```` + +This adds additional fields depending on the driver, e.g. for +`json-file` that looks like: + + "attrs":{"fizz":"buzz","foo":"bar"} + + ## syslog options The following logging options are supported for the `syslog` logging driver: @@ -100,6 +123,8 @@ The GELF logging driver supports the following options: --log-opt gelf-address=udp://host:port --log-opt tag="database" + --log-opt labels=label1,label2 + --log-opt env=env1,env2 The `gelf-address` option specifies the remote GELF server address that the driver connects to. Currently, only `udp` is supported as the transport and you must @@ -112,6 +137,15 @@ By default, Docker uses the first 12 characters of the container ID to tag log m Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. +The `labels` and `env` options are supported by the gelf logging +driver. It adds additional key on the `extra` fields, prefixed by an +underscore (`_`). + + // […] + "_foo": "bar", + "_fizz": "buzz", + // […] + ## fluentd options @@ -128,6 +162,7 @@ If container cannot connect to the Fluentd daemon on the specified address, the container stops immediately. For detailed information on working with this logging driver, see [the fluentd logging driver](fluentd.md) + ## Specify Amazon CloudWatch Logs options The Amazon CloudWatch Logs logging driver supports the following options: