kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

cleanup logging driver documentation

Browse source 
This does a minor cleanup of the logging driver
documentation;

- Add a table-header to the driver-options
  table.
- Add language hints to code-blocks to
  prevent incorrect highlighting
- Wrap some code examples so that they
  fit in the default layout
- Wrap text to 80-chars
- Fix ordering in menu
- Some minor rewording

We should still create separate pages
for all available drivers (for example,
json-file, syslog, and GELF don't have
their own configuration page)

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2016-06-01 13:18:25 +02:00
parent 41232e4b36
commit a9f6d93099
No known key found for this signature in database
GPG key ID: 76698F39D527CE8C
7 changed files with 158 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/admin/logging/etwlogs.md
View file

@ -5,7 +5,6 @@ description = "Describes how to use the etwlogs logging driver."
keywords = ["ETW, docker, logging, driver"] keywords = ["ETW, docker, logging, driver"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight=2
+++ +++
<![end-metadata]--> <![end-metadata]-->

1
docs/admin/logging/fluentd.md
View file

@ -6,7 +6,6 @@ description = "Describes how to use the fluentd logging driver."
keywords = ["Fluentd, docker, logging, driver"] keywords = ["Fluentd, docker, logging, driver"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight=2
+++ +++
<![end-metadata]--> <![end-metadata]-->

1
docs/admin/logging/gcplogs.md
View file

@ -5,7 +5,6 @@ description = "Describes how to use the Google Cloud Logging driver."
keywords = ["gcplogs, google, docker, logging, driver"] keywords = ["gcplogs, google, docker, logging, driver"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight = 2
+++ +++
<![end-metadata]--> <![end-metadata]-->

5
docs/admin/logging/journald.md
View file

@ -1,12 +1,11 @@
<!--[metadata]> <!--[metadata]>
+++ +++
aliases = ["/engine/reference/logging/journald/"] aliases = ["/engine/reference/logging/journald/"]
title = "journald logging driver" title = "Journald logging driver"
description = "Describes how to use the fluentd logging driver." description = "Describes how to use the fluentd logging driver."
keywords = ["Fluentd, docker, logging, driver"] keywords = ["Journald, docker, logging, driver"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight = 2
+++ +++
<![end-metadata]--> <![end-metadata]-->

2
docs/admin/logging/log_tags.md
View file

@ -6,7 +6,7 @@ description = "Describes how to format tags for."
keywords = ["docker, logging, driver, syslog, Fluentd, gelf, journald"] keywords = ["docker, logging, driver, syslog, Fluentd, gelf, journald"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight = 1 weight = -1
+++ +++
<![end-metadata]--> <![end-metadata]-->

259
docs/admin/logging/overview.md
View file

@ -6,7 +6,7 @@ description = "Configure logging driver."
keywords = ["docker, logging, driver, Fluentd"] keywords = ["docker, logging, driver, Fluentd"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight=-1 weight=-99
+++ +++
<![end-metadata]--> <![end-metadata]-->
@ -15,10 +15,13 @@ weight=-1
The container can have a different logging driver than the Docker daemon. Use 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 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. | | `json-file` | Default logging driver for Docker. Writes JSON messages to file. |
| `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | | `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. |
| `journald` | Journald logging driver for Docker. Writes log messages to `journald`. | | `journald` | Journald logging driver for Docker. Writes log messages to `journald`. |
@ -32,70 +35,93 @@ container's logging driver. The following options are supported:
The `docker logs`command is available only for the `json-file` and `journald` The `docker logs`command is available only for the `json-file` and `journald`
logging drivers. 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:
``` ```bash
docker daemon --log-driver=json-file --log-opt labels=foo --log-opt env=foo,fizz $ 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:
``` ```bash
docker run --label foo=bar -e fizz=buzz -d -P training/webapp python app.py $ 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 This adds additional fields to the log depending on the driver, e.g. for
`json-file` that looks like: `json-file` that looks like:
"attrs":{"fizz":"buzz","foo":"bar"} ```json
"attrs":{"fizz":"buzz","foo":"bar"}
```
## json-file options ## json-file options
The following logging options are supported for the `json-file` logging driver: The following logging options are supported for the `json-file` logging driver:
--log-opt max-size=[0-9+][k|m|g] ```bash
--log-opt max-file=[0-9+] --log-opt max-size=[0-9+][k|m|g]
--log-opt labels=label1,label2 --log-opt max-file=[0-9+]
--log-opt env=env1,env2 --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 ## syslog options
The following logging options are supported for the `syslog` logging driver: The following logging options are supported for the `syslog` logging driver:
--log-opt syslog-address=[tcp|udp|tcp+tls]://host:port ```bash
--log-opt syslog-address=unix://path --log-opt syslog-address=[tcp|udp|tcp+tls]://host:port
--log-opt syslog-address=unixgram://path --log-opt syslog-address=unix://path
--log-opt syslog-facility=daemon --log-opt syslog-address=unixgram://path
--log-opt syslog-tls-ca-cert=/etc/ca-certificates/custom/ca.pem --log-opt syslog-facility=daemon
--log-opt syslog-tls-cert=/etc/ca-certificates/custom/cert.pem --log-opt syslog-tls-ca-cert=/etc/ca-certificates/custom/ca.pem
--log-opt syslog-tls-key=/etc/ca-certificates/custom/key.pem --log-opt syslog-tls-cert=/etc/ca-certificates/custom/cert.pem
--log-opt syslog-tls-skip-verify=true --log-opt syslog-tls-key=/etc/ca-certificates/custom/key.pem
--log-opt tag="mailer" --log-opt syslog-tls-skip-verify=true
--log-opt syslog-format=[rfc5424|rfc5424micro|rfc3164] --log-opt tag="mailer"
--log-opt env=ENV1,ENV2,ENV3 --log-opt syslog-format=[rfc5424|rfc5424micro|rfc3164]
--log-opt labels=label1,label2,label3 --log-opt env=ENV1,ENV2,ENV3
--log-opt labels=label1,label2,label3
```
`syslog-address` specifies the remote syslog server address where the driver connects to. `syslog-address` specifies the remote syslog server address where the driver
If not specified it defaults to the local unix socket of the running system. connects to. If not specified it defaults to the local unix socket of the
If transport is either `tcp` or `udp` and `port` is not specified it defaults to `514` running system. If transport is either `tcp` or `udp` and `port` is not
The following example shows how to have the `syslog` driver connect to a `syslog` specified it defaults to `514` The following example shows how to have the
remote server at `192.168.0.42` on port `123` `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 The `syslog-facility` option configures the syslog facility. By default, the
`daemon` value. To override this behavior, you can provide an integer of 0 to 23 or any of system uses the `daemon` value. To override this behavior, you can provide an
the following named facilities: integer of 0 to 23 or any of the following named facilities:
* `kern` * `kern`
* `user` * `user`
@ -119,62 +145,71 @@ the following named facilities:
* `local7` * `local7`
`syslog-tls-ca-cert` specifies the absolute path to the trust certificates `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`. This option is ignored if the address protocol is not `tcp+tls`.
`syslog-tls-key` specifies the absolute path to the TLS key file. `tag` configures a string that is appended to the APP-NAME in the syslog
This option is ignored if the address protocol is not `tcp+tls`. message. 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.
`syslog-tls-skip-verify` configures the TLS verification. `syslog-format` specifies syslog message format to use when logging. If not
This verification is enabled by default, but it can be overriden by setting specified it defaults to the local unix syslog format without hostname
this option to `true`. This option is ignored if the address protocol is not `tcp+tls`. specification. Specify rfc3164 to perform logging in RFC-3164 compatible
format. Specify rfc5424 to perform logging in RFC-5424 compatible format.
Specify rfc5424micro to perform logging in RFC-5424 compatible format with
microsecond timestamp resolution.
`tag` configures a string that is appended to the APP-NAME in the syslog message. `env` is a comma-separated list of keys of environment variables. Used for
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.
`syslog-format` specifies syslog message format to use when logging.
If not specified it defaults to the local unix syslog format without hostname specification.
Specify rfc3164 to perform logging in RFC-3164 compatible format. Specify rfc5424 to perform
logging in RFC-5424 compatible format. Specify rfc5424micro to perform logging in RFC-5424
compatible format with microsecond timestamp resolution.
`env` should be a comma-separated list of keys of environment variables. Used for
advanced [log tag options](log_tags.md). advanced [log tag options](log_tags.md).
`labels` should be a comma-separated list of keys of labels. Used for advanced `labels` is a comma-separated list of keys of labels. Used for advanced [log
[log tag options](log_tags.md). tag options](log_tags.md).
## journald options ## journald options
The `journald` logging driver stores the container id in the journal's `CONTAINER_ID` field. For detailed information on The `journald` logging driver stores the container id in the journal's
working with this logging driver, see [the journald logging driver](journald.md) `CONTAINER_ID` field. For detailed information on working with this logging
reference documentation. driver, see [the journald logging driver](journald.md) reference documentation.
## gelf options ## GELF options
The GELF logging driver supports the following options: The GELF logging driver supports the following options:
--log-opt gelf-address=udp://host:port ```bash
--log-opt tag="database" --log-opt gelf-address=udp://host:port
--log-opt labels=label1,label2 --log-opt tag="database"
--log-opt env=env1,env2 --log-opt labels=label1,label2
--log-opt gelf-compression-type=gzip --log-opt env=env1,env2
--log-opt gelf-compression-level=1 --log-opt gelf-compression-type=gzip
--log-opt gelf-compression-level=1
```
The `gelf-address` option specifies the remote GELF server address that the 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 driver connects to. Currently, only `udp` is supported as the transport and you
specify a `port` value. The following example shows how to connect the `gelf` must specify a `port` value. The following example shows how to connect the
driver to a GELF remote server at `192.168.0.42` on port `12201` `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. By default, Docker uses the first 12 characters of the container ID to tag log
Refer to the [log tag option documentation](log_tags.md) for customizing messages. Refer to the [log tag option documentation](log_tags.md) for
the log tag format. customizing the log tag format.
The `labels` and `env` options are supported by the gelf logging The `labels` and `env` options are supported by the gelf logging
driver. It adds additional key on the `extra` fields, prefixed by an driver. It adds additional key on the `extra` fields, prefixed by an
@ -189,14 +224,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`. compresses each log message. The accepted values are `gzip`, `zlib` and `none`.
`gzip` is chosen by default. `gzip` is chosen by default.
The `gelf-compression-level` option can be used to change the level of compresssion The `gelf-compression-level` option can be used to change the level of
when `gzip` or `zlib` is selected as `gelf-compression-type`. Accepted value compresssion when `gzip` or `zlib` is selected as `gelf-compression-type`.
must be from from -1 to 9 (BestCompression). Higher levels typically Accepted value must be from from -1 to 9 (BestCompression). Higher levels
run slower but compress more. Default value is 1 (BestSpeed). 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] - `fluentd-address`: specify `host:port` to connect [localhost:24224]
- `tag`: specify tag for `fluentd` message - `tag`: specify tag for `fluentd` message
@ -207,7 +243,13 @@ You can use the `--log-opt NAME=VALUE` flag to specify these additional Fluentd
For example, to specify both additional options: 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 If container cannot connect to the Fluentd daemon on the specified address and
`fluentd-async-connect` is not enabled, the container stops immediately. `fluentd-async-connect` is not enabled, the container stops immediately.
@ -215,42 +257,51 @@ For detailed information on working with this logging driver,
see [the fluentd logging driver](fluentd.md) 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: The Amazon CloudWatch Logs logging driver supports the following options:
--log-opt awslogs-region=<aws_region> ```bash
--log-opt awslogs-group=<log_group_name> --log-opt awslogs-region=<aws_region>
--log-opt awslogs-stream=<log_stream_name> --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
For detailed information on working with this logging driver, see [the awslogs logging driver](awslogs.md) reference documentation. logging driver](awslogs.md) reference documentation.
## Splunk options ## Splunk options
The Splunk logging driver requires the following options: The Splunk logging driver requires the following options:
--log-opt splunk-token=<splunk_http_event_collector_token> ```bash
--log-opt splunk-url=https://your_splunk_instance:8088 --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) For detailed information about working with this logging driver, see the
reference documentation. [Splunk logging driver](splunk.md) reference documentation.
## ETW logging driver options ## ETW logging driver options
The etwlogs logging driver does not require any options to be specified. This logging driver will forward each log message The etwlogs logging driver does not require any options to be specified. This
as an ETW event. An ETW listener can then be created to listen for these events. 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: The Google Cloud Logging driver supports the following options:
--log-opt gcp-project=<gcp_projext> ```bash
--log-opt labels=<label1>,<label2> --log-opt gcp-project=<gcp_projext>
--log-opt env=<envvar1>,<envvar2> --log-opt labels=<label1>,<label2>
--log-opt log-cmd=true --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). For detailed information about working with this logging driver, see the
reference documentation. [Google Cloud Logging driver](gcplogs.md). reference documentation.

1
docs/admin/logging/splunk.md
View file

@ -6,7 +6,6 @@ description = "Describes how to use the Splunk logging driver."
keywords = ["splunk, docker, logging, driver"] keywords = ["splunk, docker, logging, driver"]
[menu.main] [menu.main]
parent = "smn_logging" parent = "smn_logging"
weight = 2
+++ +++
<![end-metadata]--> <![end-metadata]-->