From cc68a963e05540c2f39f4d5445cd6350b39e536d Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 1 Jun 2016 17:55:24 +0200 Subject: [PATCH] Merge pull request #23165 from thaJeztah/update-logging-code-hints cleanup logging driver documentation (cherry picked from commit 8d75709f90ba9926d41cd7b91bb316e336af8f8c) Signed-off-by: Sebastiaan van Stijn --- docs/admin/logging/etwlogs.md | 1 - docs/admin/logging/fluentd.md | 1 - docs/admin/logging/gcplogs.md | 1 - docs/admin/logging/journald.md | 5 +- docs/admin/logging/log_tags.md | 2 +- docs/admin/logging/overview.md | 209 ++++++++++++++++++++------------- docs/admin/logging/splunk.md | 1 - 7 files changed, 131 insertions(+), 89 deletions(-) diff --git a/docs/admin/logging/etwlogs.md b/docs/admin/logging/etwlogs.md index 5b98fd5495..17fb65ae51 100644 --- a/docs/admin/logging/etwlogs.md +++ b/docs/admin/logging/etwlogs.md @@ -5,7 +5,6 @@ description = "Describes how to use the etwlogs logging driver." keywords = ["ETW, docker, logging, driver"] [menu.main] parent = "smn_logging" -weight=2 +++ diff --git a/docs/admin/logging/fluentd.md b/docs/admin/logging/fluentd.md index 538af7b1b2..21d4b74c56 100644 --- a/docs/admin/logging/fluentd.md +++ b/docs/admin/logging/fluentd.md @@ -6,7 +6,6 @@ description = "Describes how to use the fluentd logging driver." keywords = ["Fluentd, docker, logging, driver"] [menu.main] parent = "smn_logging" -weight=2 +++ diff --git a/docs/admin/logging/gcplogs.md b/docs/admin/logging/gcplogs.md index 08fd858da0..c92c17a102 100644 --- a/docs/admin/logging/gcplogs.md +++ b/docs/admin/logging/gcplogs.md @@ -5,7 +5,6 @@ description = "Describes how to use the Google Cloud Logging driver." keywords = ["gcplogs, google, docker, logging, driver"] [menu.main] parent = "smn_logging" -weight = 2 +++ diff --git a/docs/admin/logging/journald.md b/docs/admin/logging/journald.md index 90c9720319..8476dd062f 100644 --- a/docs/admin/logging/journald.md +++ b/docs/admin/logging/journald.md @@ -1,12 +1,11 @@ diff --git a/docs/admin/logging/log_tags.md b/docs/admin/logging/log_tags.md index 9b2e098d9f..41297d97a8 100644 --- a/docs/admin/logging/log_tags.md +++ b/docs/admin/logging/log_tags.md @@ -6,7 +6,7 @@ description = "Describes how to format tags for." keywords = ["docker, logging, driver, syslog, Fluentd, gelf, journald"] [menu.main] parent = "smn_logging" -weight = 1 +weight = -1 +++ diff --git a/docs/admin/logging/overview.md b/docs/admin/logging/overview.md index 8a7cd12ffb..0c8c0e7b44 100644 --- a/docs/admin/logging/overview.md +++ b/docs/admin/logging/overview.md @@ -6,7 +6,7 @@ description = "Configure logging driver." keywords = ["docker, logging, driver, Fluentd"] [menu.main] parent = "smn_logging" -weight=-1 +weight=-99 +++ @@ -15,10 +15,13 @@ weight=-1 The container can have a different logging driver than the Docker daemon. Use the `--log-driver=VALUE` with the `docker run` command to configure the -container's logging driver. The following options are supported: +container's logging driver. If the `--log-driver` option is not set, docker +uses the default (`json-file`) logging driver. The following options are +supported: -| `none` | Disables any logging for the container. `docker logs` won't be available with this driver. | +| Driver | Description | |-------------|-------------------------------------------------------------------------------------------------------------------------------| +| `none` | Disables any logging for the container. `docker logs` won't be available with this driver. | | `json-file` | Default logging driver for Docker. Writes JSON messages to file. | | `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | | `journald` | Journald logging driver for Docker. Writes log messages to `journald`. | @@ -32,40 +35,58 @@ container's logging driver. The following options are supported: The `docker logs`command is available only for the `json-file` and `journald` logging drivers. -The `labels` and `env` options add additional attributes for use with logging drivers that accept them. Each option takes a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence. +The `labels` and `env` options add additional attributes for use with logging +drivers that accept them. Each option 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. +To use attributes, specify them when you start the Docker daemon. For example, +to manually start the daemon with the `json-file` driver, and include additional +attributes in the output, run the following command: -``` -docker daemon --log-driver=json-file --log-opt labels=foo --log-opt env=foo,fizz +```bash +$ 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: +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 +```bash +$ docker run -dit --label foo=bar -e fizz=buzz alpine sh ``` This adds additional fields to the log depending on the driver, e.g. for `json-file` that looks like: - "attrs":{"fizz":"buzz","foo":"bar"} +```json +"attrs":{"fizz":"buzz","foo":"bar"} +``` ## 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 +```bash +--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. +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. -`max-file` specifies the maximum number of files that a log is rolled over before being discarded. eg `--log-opt max-file=100`. If `max-size` is not set, then `max-file` is not honored. +`max-file` specifies the maximum number of files that a log is rolled over +before being discarded. eg `--log-opt max-file=100`. If `max-size` is not set, +then `max-file` is not honored. -If `max-size` and `max-file` are set, `docker logs` only returns the log lines from the newest log file. +If `max-size` and `max-file` are set, `docker logs` only returns the log lines +from the newest log file. ## syslog options @@ -82,17 +103,20 @@ The following logging options are supported for the `syslog` logging driver: --log-opt tag="mailer" --log-opt syslog-format=[rfc5424|rfc3164] -`syslog-address` specifies the remote syslog server address where the driver connects to. -If not specified it defaults to the local unix socket of the running system. -If transport is either `tcp` or `udp` and `port` is not specified it defaults to `514` -The following example shows how to have the `syslog` driver connect to a `syslog` -remote server at `192.168.0.42` on port `123` +`syslog-address` specifies the remote syslog server address where the driver +connects to. If not specified it defaults to the local unix socket of the +running system. If transport is either `tcp` or `udp` and `port` is not +specified it defaults to `514` The following example shows how to have the +`syslog` driver connect to a `syslog` remote server at `192.168.0.42` on port +`123` - $ docker run --log-driver=syslog --log-opt syslog-address=tcp://192.168.0.42:123 +```bash +$ docker run --log-driver=syslog --log-opt syslog-address=tcp://192.168.0.42:123 +``` -The `syslog-facility` option configures the syslog facility. By default, the system uses the -`daemon` value. To override this behavior, you can provide an integer of 0 to 23 or any of -the following named facilities: +The `syslog-facility` option configures the syslog facility. By default, the +system uses the `daemon` value. To override this behavior, you can provide an +integer of 0 to 23 or any of the following named facilities: * `kern` * `user` @@ -116,18 +140,19 @@ the following named facilities: * `local7` `syslog-tls-ca-cert` specifies the absolute path to the trust certificates -signed by the CA. This option is ignored if the address protocol is not `tcp+tls`. +signed by the CA. This option is ignored if the address protocol is not +`tcp+tls`. -`syslog-tls-cert` specifies the absolute path to the TLS certificate file. +`syslog-tls-cert` specifies the absolute path to the TLS certificate file. This +option is ignored if the address protocol is not `tcp+tls`. + +`syslog-tls-key` specifies the absolute path to the TLS key file. This option +is ignored if the address protocol is not `tcp+tls`. + +`syslog-tls-skip-verify` configures the TLS verification. This verification is +enabled by default, but it can be overriden by setting this option to `true`. This option is ignored if the address protocol is not `tcp+tls`. -`syslog-tls-key` specifies the absolute path to the TLS key file. -This option is ignored if the address protocol is not `tcp+tls`. - -`syslog-tls-skip-verify` configures the TLS verification. -This verification is enabled by default, but it can be overriden by setting -this option to `true`. This option is ignored if the address protocol is not `tcp+tls`. - By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. @@ -137,34 +162,40 @@ If not specified it defaults to the local unix syslog format without hostname sp Specify rfc3164 to perform logging in RFC-3164 compatible format. Specify rfc5424 to perform logging in RFC-5424 compatible format - ## journald options -The `journald` logging driver stores the container id in the journal's `CONTAINER_ID` field. For detailed information on -working with this logging driver, see [the journald logging driver](journald.md) -reference documentation. +The `journald` logging driver stores the container id in the journal's +`CONTAINER_ID` field. For detailed information on working with this logging +driver, see [the journald logging driver](journald.md) reference documentation. -## gelf options +## GELF options 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 - --log-opt gelf-compression-type=gzip - --log-opt gelf-compression-level=1 +```bash +--log-opt gelf-address=udp://host:port +--log-opt tag="database" +--log-opt labels=label1,label2 +--log-opt env=env1,env2 +--log-opt gelf-compression-type=gzip +--log-opt gelf-compression-level=1 +``` 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 -specify a `port` value. The following example shows how to connect the `gelf` -driver to a GELF remote server at `192.168.0.42` on port `12201` +driver connects to. Currently, only `udp` is supported as the transport and you +must specify a `port` value. The following example shows how to connect the +`gelf` driver to a GELF remote server at `192.168.0.42` on port `12201` - $ docker run --log-driver=gelf --log-opt gelf-address=udp://192.168.0.42:12201 +```bash +$ docker run -dit \ + --log-driver=gelf \ + --log-opt gelf-address=udp://192.168.0.42:12201 \ + alpine sh +``` -By default, Docker uses the first 12 characters of the container ID to tag log messages. -Refer to the [log tag option documentation](log_tags.md) for customizing -the log tag format. +By default, Docker uses the first 12 characters of the container ID to tag log +messages. 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 @@ -179,14 +210,15 @@ The `gelf-compression-type` option can be used to change how the GELF driver compresses each log message. The accepted values are `gzip`, `zlib` and `none`. `gzip` is chosen by default. -The `gelf-compression-level` option can be used to change the level of compresssion -when `gzip` or `zlib` is selected as `gelf-compression-type`. Accepted value -must be from from -1 to 9 (BestCompression). Higher levels typically -run slower but compress more. Default value is 1 (BestSpeed). +The `gelf-compression-level` option can be used to change the level of +compresssion when `gzip` or `zlib` is selected as `gelf-compression-type`. +Accepted value must be from from -1 to 9 (BestCompression). Higher levels +typically run slower but compress more. Default value is 1 (BestSpeed). -## fluentd options +## Fluentd options -You can use the `--log-opt NAME=VALUE` flag to specify these additional Fluentd logging driver options. +You can use the `--log-opt NAME=VALUE` flag to specify these additional Fluentd +logging driver options. - `fluentd-address`: specify `host:port` to connect [localhost:24224] - `tag`: specify tag for `fluentd` message @@ -197,7 +229,13 @@ You can use the `--log-opt NAME=VALUE` flag to specify these additional Fluentd For example, to specify both additional options: -`docker run --log-driver=fluentd --log-opt fluentd-address=localhost:24224 --log-opt tag=docker.{{.Name}}` +```bash +$ docker run -dit \ + --log-driver=fluentd \ + --log-opt fluentd-address=localhost:24224 \ + --log-opt tag="docker.{{.Name}}" \ + alpine sh +``` If container cannot connect to the Fluentd daemon on the specified address and `fluentd-async-connect` is not enabled, the container stops immediately. @@ -205,42 +243,51 @@ For detailed information on working with this logging driver, see [the fluentd logging driver](fluentd.md) -## Specify Amazon CloudWatch Logs options +## Amazon CloudWatch Logs options The Amazon CloudWatch Logs logging driver supports the following options: - --log-opt awslogs-region= - --log-opt awslogs-group= - --log-opt awslogs-stream= +```bash +--log-opt awslogs-region= +--log-opt awslogs-group= +--log-opt awslogs-stream= +``` - -For detailed information on working with this logging driver, see [the awslogs logging driver](awslogs.md) reference documentation. +For detailed information on working with this logging driver, see [the awslogs +logging driver](awslogs.md) reference documentation. ## Splunk options The Splunk logging driver requires the following options: - --log-opt splunk-token= - --log-opt splunk-url=https://your_splunk_instance:8088 +```bash +--log-opt splunk-token= +--log-opt splunk-url=https://your_splunk_instance:8088 +``` -For detailed information about working with this logging driver, see the [Splunk logging driver](splunk.md) -reference documentation. +For detailed information about working with this logging driver, see the +[Splunk logging driver](splunk.md) reference documentation. ## ETW logging driver options -The etwlogs logging driver does not require any options to be specified. This logging driver will forward each log message -as an ETW event. An ETW listener can then be created to listen for these events. +The etwlogs logging driver does not require any options to be specified. This +logging driver forwards each log message as an ETW event. An ETW listener +can then be created to listen for these events. -For detailed information on working with this logging driver, see [the ETW logging driver](etwlogs.md) reference documentation. +The ETW logging driver is only available on Windows. For detailed information +on working with this logging driver, see [the ETW logging driver](etwlogs.md) +reference documentation. -## Google Cloud Logging +## Google Cloud Logging options The Google Cloud Logging driver supports the following options: - --log-opt gcp-project= - --log-opt labels=, - --log-opt env=, - --log-opt log-cmd=true +```bash +--log-opt gcp-project= +--log-opt labels=, +--log-opt env=, +--log-opt log-cmd=true +``` -For detailed information about working with this logging driver, see the [Google Cloud Logging driver](gcplogs.md). -reference documentation. +For detailed information about working with this logging driver, see the +[Google Cloud Logging driver](gcplogs.md). reference documentation. diff --git a/docs/admin/logging/splunk.md b/docs/admin/logging/splunk.md index 9c60a529d2..b5f60f3450 100644 --- a/docs/admin/logging/splunk.md +++ b/docs/admin/logging/splunk.md @@ -6,7 +6,6 @@ description = "Describes how to use the Splunk logging driver." keywords = ["splunk, docker, logging, driver"] [menu.main] parent = "smn_logging" -weight = 2 +++