diff --git a/docs/reference/logging/fluentd.md b/docs/reference/logging/fluentd.md new file mode 100644 index 0000000000..71af9f0b7f --- /dev/null +++ b/docs/reference/logging/fluentd.md @@ -0,0 +1,109 @@ + + +# Fluentd logging driver + +The `fluentd` logging driver sends container logs to the +[Fluentd](http://www.fluentd.org/) collector as structured log data. Then, users +can use any of the [various output plugins of +Fluentd](http://www.fluentd.org/plugins) to write these logs to various +destinations. + +In addition to the log message itself, the `fluentd` log +driver sends the following metadata in the structured log message: + +| Field | Description | +-------------------|-------------------------------------| +| `container_id` | The full 64-character container ID. | +| `container_name` | The container name at the time it was started. If you use `docker rename` to rename a container, the new name is not reflected in the journal entries. | +| `source` | `stdout` or `stderr` | + +## Usage + +Configure the default logging driver by passing the +`--log-driver` option to the Docker daemon: + + docker --log-driver=fluentd + +To set the logging driver for a specific container, pass the +`--log-driver` option to `docker run`: + + docker run --log-driver=fluentd ... + +Before using this logging driver, launch a Fluentd daemon. The logging driver +connects to this daemon through `localhost:24224` by default. Use the +`fluentd-address` option to connect to a different address. + + docker run --log-driver=fluentd --log-opt fluentd-address=myhost.local:24224 + +If container cannot connect to the Fluentd daemon, the container stops +immediately. + +## Options + +Users can use the `--log-opt NAME=VALUE` flag to specify additional Fluentd logging driver options. + +### fluentd-address + +By default, the logging driver connects to `localhost:24224`. Supply the +`fluentd-address` option to connect to a different address. + + docker run --log-driver=fluentd --log-opt fluentd-address=myhost.local:24224 + +### fluentd-tag + +Every Fluentd's event has a tag that indicates where the log comes from. By +default, the driver uses the `docker.{{.ID}}` tag. Use the `fluentd-tag` option +to change this behavior. + +When specifying a `fluentd-tag` value, you can use the following markup tags: + + - `{{.ID}}`: short container id (12 characters) + - `{{.FullID}}`: full container id + - `{{.Name}}`: container name + +## Note regarding container names + +At startup time, the system sets the `container_name` field and `{{.Name}}` +in the tags to their values at startup. If you use `docker rename` to rename a +container, the new name is not be reflected in `fluentd` messages. Instead, +these messages continue to use the original container name. + +## Fluentd daemon management with Docker + +About `Fluentd` itself, see [the project webpage](http://www.fluentd.org) +and [its documents](http://docs.fluentd.org/). + +To use this logging driver, start the `fluentd` daemon on a host. We recommend +that you use [the Fluentd docker +image](https://registry.hub.docker.com/u/fluent/fluentd/). This image is +especially useful if you want to aggregate multiple container logs on a each +host then, later, transfer the logs to another Fluentd node to create an +aggregate store. + +### Testing container loggers + +1. Write a configuration file (`test.conf`) to dump input logs: + + + @type forward + + + + @type stdout + + +2. Launch Fluentd container with this configuration file: + + $ docker run -it -p 24224:24224 -v /path/to/conf/test.conf:/fluentd/etc -e FLUENTD_CONF=test.conf fluent/fluentd:latest + +3. Start one or more containers with the `fluentd` logging driver: + + $ docker run --log-driver=fluentd your/application diff --git a/docs/reference/logging/index.md b/docs/reference/logging/index.md new file mode 100644 index 0000000000..e50d320910 --- /dev/null +++ b/docs/reference/logging/index.md @@ -0,0 +1,115 @@ + + + +# Configure logging drivers + +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: + +| `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. No logging options are supported for this driver. | +| `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | +| `journald` | Journald logging driver for Docker. Writes log messages to `journald`. | +| `gelf` | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. | +| `fluentd` | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input). | + +The `docker logs`command is available only for the `json-file` logging driver. + +### The syslog options + +The following logging options are supported for the `syslog` logging driver: + + --log-opt syslog-address=[tcp|udp]://host:port + --log-opt syslog-address=unix://path + --log-opt syslog-facility=daemon + --log-opt syslog-tag="mailer" + +`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 + +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` +* `mail` +* `daemon` +* `auth` +* `syslog` +* `lpr` +* `news` +* `uucp` +* `cron` +* `authpriv` +* `ftp` +* `local0` +* `local1` +* `local2` +* `local3` +* `local4` +* `local5` +* `local6` +* `local7` + +The `syslog-tag` specifies a tag that identifies the container's syslog messages. By default, +the system uses the first 12 characters of the container id. To override this behavior, specify +a `syslog-tag` option + +## Specify journald options + +The `journald` logging driver sotres the container id in the journal's `CONTAINER_ID` field. For detailed information on +working with this logging driver, see [the journald logging driver](/reference/logging/journald/) +reference documentation. + +## Specify gelf options + +The GELF logging driver supports the following options: + + --log-opt gelf-address=udp://host:port + --log-opt gelf-tag="database" + +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` + + $ docker run --log-driver=gelf --log-opt gelf-address=udp://192.168.0.42:12201 + +The `gelf-tag` option specifies a tag for easy container identification. + +## Specify fluentd 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-tag`: specify tag for `fluentd` message, + +When specifying a `fluentd-tag` value, you can use the following markup tags: + + - `{{.ID}}`: short container id (12 characters) + - `{{.FullID}}`: full container id + - `{{.Name}}`: container name + +For example, to specify both additional options: + +`docker run --log-driver=fluentd --log-opt fluentd-address=localhost:24224 --log-opt fluentd-tag=docker.{{.Name}}` + +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 journald logging driver](/reference/logging/fluentd/) diff --git a/docs/reference/logging/journald.md b/docs/reference/logging/journald.md index 9c025bfe62..b502971634 100644 --- a/docs/reference/logging/journald.md +++ b/docs/reference/logging/journald.md @@ -1,3 +1,13 @@ + + # Journald logging driver The `journald` logging driver sends container logs to the [systemd diff --git a/docs/reference/run.md b/docs/reference/run.md index 556ec23e16..c50dd22c46 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -866,99 +866,23 @@ familiar with using LXC directly. > you can use `--lxc-conf` to set a container's IP address, but this will not be > reflected in the `/etc/hosts` file. -## Logging drivers (--log-driver) +# Logging drivers (--log-driver) -You can specify a different logging driver for the container than for the daemon. +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: -#### Logging driver: none +| `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. No logging options are supported for this driver. | +| `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | +| `journald` | Journald logging driver for Docker. Writes log messages to `journald`. | +| `gelf` | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. | +| `fluentd` | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input). | -Disables any logging for the container. `docker logs` won't be available with -this driver. - -#### Logging driver: json-file - -Default logging driver for Docker. Writes JSON messages to file. `docker logs` -command is available only for this logging driver - -The following logging options are supported for this logging driver: [none] - -#### Logging driver: syslog - -Syslog logging driver for Docker. Writes log messages to syslog. `docker logs` -command is not available for this logging driver - -The following logging options are supported for this logging driver: - - --log-opt syslog-address=[tcp|udp]://host:port - --log-opt syslog-address=unix://path - --log-opt syslog-facility=daemon - --log-opt syslog-tag="mailer" - -`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 - -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` -* `mail` -* `daemon` -* `auth` -* `syslog` -* `lpr` -* `news` -* `uucp` -* `cron` -* `authpriv` -* `ftp` -* `local0` -* `local1` -* `local2` -* `local3` -* `local4` -* `local5` -* `local6` -* `local7` - -The `syslog-tag` specifies a tag that identifies the container's syslog messages. By default, -the system uses the first 12 characters of the container id. To override this behavior, specify -a `syslog-tag` option - -#### Logging driver: journald - -Journald logging driver for Docker. Writes log messages to journald; the -container id will be stored in the journal's `CONTAINER_ID` field. `docker logs` -command is not available for this logging driver. For detailed information on -working with this logging driver, see [the journald logging driver](reference/logging/journald) -reference documentation. - -The following logging options are supported for this logging driver: [none] - -#### Logging driver: gelf - -Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint like -Graylog or Logstash. The `docker logs` command is not available for this logging driver. - -The GELF logging driver supports the following options: - - --log-opt gelf-address=udp://host:port - --log-opt gelf-tag="database" - -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` - - $ docker run --log-driver=gelf --log-opt gelf-address=udp://192.168.0.42:12201 - -The `gelf-tag` option specifies a tag for easy container identification. + The `docker logs`command is available only for the `json-file` logging +driver. For detailed information on working with logging drivers, see +[Configure a logging driver](reference/logging/). ## Overriding Dockerfile image defaults