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 <lars@redhat.com>

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
 		}

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
 }
 

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']

docs/sources/reference.md

@@ -3,6 +3,7 @@
 ## Contents:
 
  - [Commands](commandline/)
+ - [Logging drivers](logging/)
  - [Dockerfile Reference](builder/)
  - [Docker Run Reference](run/)
  - [APIs](api/)

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)
+

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