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 <github@gone.nl>

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
 +++
 <![end-metadata]-->
 
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
 +++
 <![end-metadata]-->
 
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
 +++
 <![end-metadata]-->
 
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 @@
 <!--[metadata]>
 +++
 aliases = ["/engine/reference/logging/journald/"]
-title = "journald logging driver"
+title = "Journald logging driver"
 description = "Describes how to use the fluentd logging driver."
-keywords = ["Fluentd, docker, logging, driver"]
+keywords = ["Journald, docker, logging, driver"]
 [menu.main]
 parent = "smn_logging"
-weight = 2
 +++
 <![end-metadata]-->
 
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
 +++
 <![end-metadata]-->
 
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
 +++
 <![end-metadata]-->
 
@@ -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,17 +140,18 @@ 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.
-This option is ignored if the address protocol is not `tcp+tls`.
+`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-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-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
@@ -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`
+
+```bash
+$ docker run -dit \
+    --log-driver=gelf \
+    --log-opt gelf-address=udp://192.168.0.42:12201 \
+    alpine sh
+```
 
-    $ docker run --log-driver=gelf --log-opt gelf-address=udp://192.168.0.42:12201
-
-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=<aws_region>
-    --log-opt awslogs-group=<log_group_name>
-    --log-opt awslogs-stream=<log_stream_name>
-
+```bash
+--log-opt awslogs-region=<aws_region>
+--log-opt awslogs-group=<log_group_name>
+--log-opt awslogs-stream=<log_stream_name>
+```
 
-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=<splunk_http_event_collector_token>
-    --log-opt splunk-url=https://your_splunk_instance:8088
+```bash
+--log-opt splunk-token=<splunk_http_event_collector_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=<gcp_projext>
-    --log-opt labels=<label1>,<label2>
-    --log-opt env=<envvar1>,<envvar2>
-    --log-opt log-cmd=true
+```bash
+--log-opt gcp-project=<gcp_projext>
+--log-opt labels=<label1>,<label2>
+--log-opt env=<envvar1>,<envvar2>
+--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
 +++
 <![end-metadata]-->