From 869ecba652294e069874c83591d6f1b469d7cc32 Mon Sep 17 00:00:00 2001 From: Lars Kellogg-Stedman Date: Tue, 28 Apr 2015 21:23:27 -0400 Subject: [PATCH] journald log driver: use CONTAINER_ID field for container id This patch modifies the journald log driver to store the container ID in a field named CONTAINER_ID, rather than (ab)using the MESSAGE_ID field. Additionally, this adds the CONTAINER_ID_FULL field containing the complete container ID and CONTAINER_NAME, containing the container name. When using the journald log driver, this permits you to see log messages from a particular container like this: # journalctl CONTAINER_ID=a9238443e193 Example output from "journalctl -o verbose" includes the following: CONTAINER_ID=27aae7361e67 CONTAINER_ID_FULL=27aae7361e67e2b4d3864280acd2b80e78daf8ec73786d8b68f3afeeaabbd4c4 CONTAINER_NAME=web Closes: #12864 Signed-off-by: Lars Kellogg-Stedman --- daemon/container.go | 2 +- daemon/logger/journald/journald.go | 12 +++- docs/mkdocs.yml | 1 + docs/sources/reference.md | 1 + docs/sources/reference/logging/journald.md | 66 ++++++++++++++++++++++ docs/sources/reference/run.md | 2 +- 6 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 docs/sources/reference/logging/journald.md diff --git a/daemon/container.go b/daemon/container.go index 9bd8cc1eb9..c771076084 100644 --- a/daemon/container.go +++ b/daemon/container.go @@ -1447,7 +1447,7 @@ func (container *Container) startLogging() error { } l = dl case "journald": - dl, err := journald.New(container.ID[:12]) + dl, err := journald.New(container.ID, container.Name) if err != nil { return err } diff --git a/daemon/logger/journald/journald.go b/daemon/logger/journald/journald.go index 5eb141ac83..77bd2f24fe 100644 --- a/daemon/logger/journald/journald.go +++ b/daemon/logger/journald/journald.go @@ -11,11 +11,19 @@ type Journald struct { Jmap map[string]string } -func New(id string) (logger.Logger, error) { +func New(id string, name string) (logger.Logger, error) { if !journal.Enabled() { return nil, fmt.Errorf("journald is not enabled on this host") } - jmap := map[string]string{"MESSAGE_ID": id} + // Strip a leading slash so that people can search for + // CONTAINER_NAME=foo rather than CONTAINER_NAME=/foo. + if name[0] == '/' { + name = name[1:] + } + jmap := map[string]string{ + "CONTAINER_ID": id[:12], + "CONTAINER_ID_FULL": id, + "CONTAINER_NAME": name} return &Journald{Jmap: jmap}, nil } diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fb08e289e1..7438af582b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -131,6 +131,7 @@ pages: - ['reference/builder.md', 'Reference', 'Dockerfile'] - ['faq.md', 'Reference', 'FAQ'] - ['reference/run.md', 'Reference', 'Run reference'] +- ['reference/logging/journald.md', '**HIDDEN**'] - ['compose/cli.md', 'Reference', 'Compose command line'] - ['compose/yml.md', 'Reference', 'Compose yml'] - ['compose/env.md', 'Reference', 'Compose ENV variables'] diff --git a/docs/sources/reference.md b/docs/sources/reference.md index 6c1ab462d4..8cfe304672 100644 --- a/docs/sources/reference.md +++ b/docs/sources/reference.md @@ -3,6 +3,7 @@ ## Contents: - [Commands](commandline/) + - [Logging drivers](logging/) - [Dockerfile Reference](builder/) - [Docker Run Reference](run/) - [APIs](api/) diff --git a/docs/sources/reference/logging/journald.md b/docs/sources/reference/logging/journald.md new file mode 100644 index 0000000000..9c025bfe62 --- /dev/null +++ b/docs/sources/reference/logging/journald.md @@ -0,0 +1,66 @@ +# Journald logging driver + +The `journald` logging driver sends container logs to the [systemd +journal](http://www.freedesktop.org/software/systemd/man/systemd-journald.service.html). Log entries can be retrieved using the `journalctl` +command or through use of the journal API. + +In addition to the text of the log message itself, the `journald` log +driver stores the following metadata in the journal with each message: + +| Field | Description | +----------------------|-------------| +| `CONTAINER_ID` | The container ID truncated to 12 characters. | +| `CONTAINER_ID_FULL` | 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. | + +## Usage + +You can configure the default logging driver by passing the +`--log-driver` option to the Docker daemon: + + docker --log-driver=journald + +You can set the logging driver for a specific container by using the +`--log-driver` option to `docker run`: + + docker run --log-driver=journald ... + +## Note regarding container names + +The value logged in the `CONTAINER_NAME` field is the container name +that was set at startup. If you use `docker rename` to rename a +container, the new name will not be reflected in the journal entries. +Journal entries will continue to use the original name. + +## Retrieving log messages with journalctl + +You can use the `journalctl` command to retrieve log messages. You +can apply filter expressions to limit the retrieved messages to a +specific container. For example, to retrieve all log messages from a +container referenced by name: + + # journalctl CONTAINER_NAME=webserver + +You can make use of additional filters to further limit the messages +retrieved. For example, to see just those messages generated since +the system last booted: + + # journalctl -b CONTAINER_NAME=webserver + +Or to retrieve log messages in JSON format with complete metadata: + + # journalctl -o json CONTAINER_NAME=webserver + +## Retrieving log messages with the journal API + +This example uses the `systemd` Python module to retrieve container +logs: + + import systemd.journal + + reader = systemd.journal.Reader() + reader.add_match('CONTAINER_NAME=web') + + for msg in reader: + print '{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg) + diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md index 990faaf6c0..7b05f99d94 100644 --- a/docs/sources/reference/run.md +++ b/docs/sources/reference/run.md @@ -790,7 +790,7 @@ command is not available for this logging driver #### Logging driver: journald -Journald logging driver for Docker. Writes log messages to journald. `docker logs` command is not available for this logging driver +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. ## Overriding Dockerfile image defaults