From 4e2ee1a40c428593e2a44c80a4a9cf17a3ead4a7 Mon Sep 17 00:00:00 2001 From: Nils Otto Johansen Date: Mon, 19 Dec 2016 20:15:45 +0100 Subject: [PATCH] documenting rateLimit wich leads to the confusion of #28641 (#670) * documenting rateLimit which leads to the confusion of #28641 --- engine/admin/logging/journald.md | 98 +++++++++++++++++++------------- 1 file changed, 60 insertions(+), 38 deletions(-) diff --git a/engine/admin/logging/journald.md b/engine/admin/logging/journald.md index 8dbff233ef..2afd70f056 100644 --- a/engine/admin/logging/journald.md +++ b/engine/admin/logging/journald.md @@ -6,10 +6,10 @@ redirect_from: title: 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). +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, through use of the -journal API, or using the `docker logs` command. +`journal` API, or using the `docker logs` command. In addition to the text of the log message itself, the `journald` log driver stores the following metadata in the journal with each message: @@ -24,69 +24,91 @@ stores the following metadata in the journal with each message: ## Usage -You can configure the default logging driver by passing the `--log-driver` -option to the Docker daemon: +Configure the default logging driver by passing the `--log-driver` option to the +Docker daemon: - dockerd --log-driver=journald +```bash +$ dockerd --log-driver=journald +``` -You can set the logging driver for a specific container by using the -`--log-driver` option to `docker run`: +To configure the logging driver for a specific container, use the `--log-driver` +flag on the `docker run` command. - docker run --log-driver=journald ... +```bash +$ docker run --log-driver=journald ... +``` ## Options -Users can use the `--log-opt NAME=VALUE` flag to specify additional journald -logging driver options. +Use the `--log-opt NAME=VALUE` flag to specify additional `journald` logging +driver options. -### tag +### `tag` -Specify template to set `CONTAINER_TAG` value in journald logs. Refer to -[log tag option documentation](log_tags.md) for customizing the log tag format. +Specify template to set `CONTAINER_TAG` value in `journald` logs. Refer to +[log tag option documentation](log_tags.md) to customize the log tag format. -### labels and env +### `labels` and `env` The `labels` and `env` options each take a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes -precedence. Both options add additional metadata in the journal with each +precedence. Each option adds additional metadata to the journal with each message. ## 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. +The value logged in the `CONTAINER_NAME` field is the name of the container that +was set at startup. If you use `docker rename` to rename a container, the new +name **is not reflected** in the journal entries. Journal entries will continue +to use the original name. -## Retrieving log messages with journalctl +## 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: +Use the `journalctl` command to retrieve log messages. You can apply filter +expressions to limit the retrieved messages to those associated with a specific +container: - # journalctl CONTAINER_NAME=webserver +```bash +$ sudo 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: +You can use additional filters to further limit the messages retrieved. The `-b` +flag only retrieves messages generated since the last system boot: - # journalctl -b CONTAINER_NAME=webserver +```bash +$ sudo journalctl -b CONTAINER_NAME=webserver +``` -Or to retrieve log messages in JSON format with complete metadata: +The `-o` flag specifies the format for the retried log messages. Use `-o json` +to return the log messages in JSON format. - # journalctl -o json CONTAINER_NAME=webserver +```bash +$ sudo journalctl -o json CONTAINER_NAME=webserver +``` -## Retrieving log messages with the journal API +## Retrieving log messages with the `journal` API This example uses the `systemd` Python module to retrieve container logs: - import systemd.journal +```python +import systemd.journal - reader = systemd.journal.Reader() - reader.add_match('CONTAINER_NAME=web') +reader = systemd.journal.Reader() +reader.add_match('CONTAINER_NAME=web') - for msg in reader: - print '{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg) +for msg in reader: + print '{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg) +``` +## `journald` configuration + +Docker hosts with many containers may produce large amounts of logging data. +By default, `journald` limits the number of messages stored per service per +time-unit. + +If your application needs large-scale logging, configure `RateLimitIntervalSec` +and `RateLimitBurst` in the `journald` configuration file. By default, +`systemd` drops messages in excess of 1000 messages per service per 30 seconds. +For more information about configuring `journald`, see the +[`journald` documentation](https://www.freedesktop.org/software/systemd/man/journald.conf.html).