beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #14182 from moxiegirl/fix-logging

Browse source 
Breaking logging driver material out of run
This commit is contained in:
moxiegirl 2015-06-25 10:28:36 -07:00
commit 81d6f60935
4 changed files with 248 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
docs/reference/logging/fluentd.md Normal file
View file

@ -0,0 +1,109 @@
<!--[metadata]>
+++
title = "Fluentd logging driver"
description = "Describes how to use the fluentd logging driver."
keywords = ["Fluentd, docker, logging, driver"]
[menu.main]
parent = "smn_logging"
+++
<![end-metadata]-->
# 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:
<source>
@type forward
</source>
<match docker.**>
@type stdout
</match>
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

115
docs/reference/logging/index.md Normal file
View file

@ -0,0 +1,115 @@
<!--[metadata]>
+++
title = "Configure logging drivers"
description = "Configure logging driver."
keywords = ["Fluentd, docker, logging, driver"]
[menu.main]
parent = "smn_logging"
+++
<![end-metadata]-->
# 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/)

10
docs/reference/logging/journald.md
View file

@ -1,3 +1,13 @@
<!--[metadata]>
+++
title = "journald logging driver"
description = "Describes how to use the fluentd logging driver."
keywords = ["Fluentd, docker, logging, driver"]
[menu.main]
parent = "smn_logging"
+++
<![end-metadata]-->
# Journald logging driver
The `journald` logging driver sends container logs to the [systemd

104
docs/reference/run.md
View file

@ -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