From cc5f37872adf8ac1b34b9034c6f249b3cd467812 Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Thu, 2 Feb 2017 10:35:24 -0500 Subject: [PATCH] Adds details about new non-blocking logging mode This functionality was added in docker/docker#28762. It allows a user to specify what to do in cases when a log message can't be sent, block the container's stdio or drop messages. Also removes an erronious entry about a `nats` log driver, which does not exist. Signed-off-by: Brian Goff --- engine/admin/logging/nats.md | 88 -------------------------------- engine/admin/logging/overview.md | 8 ++- 2 files changed, 7 insertions(+), 89 deletions(-) delete mode 100644 engine/admin/logging/nats.md diff --git a/engine/admin/logging/nats.md b/engine/admin/logging/nats.md deleted file mode 100644 index 81f11ccb007..00000000000 --- a/engine/admin/logging/nats.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Describes how to use NATS for publishing log entries -keywords: NATS, nats.io, messaging, docker, logging, driver -title: NATS logging driver ---- - -Docker logging driver for sending container the logs as events published to NATS in JSON format. - -## Usage - -You can configure the default logging driver by passing the `--log-driver` -option to the Docker daemon: - -```bash -$ dockerd --log-driver=nats -``` - -You can set the logging driver for a specific container by using the -`--log-driver` option to `docker run`: - -```bash -$ docker run --log-driver=nats ... -``` - -This log driver does not implement a reader so it is incompatible with `docker logs`. - -## nats options - -You can use the `--log-opt NAME=VALUE` flag to customize the logging driver -for NATS: - -| Option | Required | Description | -|-----------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------| -| `labels` | optional | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for container. | -| `env` | optional | Comma-separated list of keys of environment variables, which should be included in message, if these variables are specified for container. | -| `tag` | optional | Specify tag for message. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. | -| `nats-servers` | optional | NATS cluster nodes separated by commas. e.g. `nats://127.0.0.1:4222,nats://127.0.0.1:4223`. Defaults to `localhost:4222` | -| `nats-max-reconnect` | optional | Maximum attempts that the driver will try to connect before giving up. Defaults to infinite (`-1`) | -| `nats-subject` | optional | Specific subject to which logs will be published. Defaults to using `tag` if not specified | -| `nats-user` | optional | Specify user in case of authentication required | -| `nats-pass` | optional | Specify password in case of authentication required | -| `nats-token` | optional | Specify token in case of authentication required | -| `nats-tls-ca-cert` | optional | Specified the absolute path to the trust certificates signed by the CA | -| `nats-tls-cert` | optional | Specifies the absolute path to the TLS certificate file | -| `nats-tls-key` | optional | Specifies the absolute path to the TLS key file | -| `nats-tls-skip-verify` | optional | Specifies whether to skip verification by setting it to `true` | - -Below is an example usage of the driver for sending logs to a node in a -NATS cluster to the `docker.logs` subject: - -```bash -$ docker run --log-driver=nats \ - --log-opt nats-subject=docker.logs \ - --log-opt nats-servers=nats://nats-node-1:4222,nats://nats-node-2:4222,nats://nats-node-3:4222 \ - your/application -``` - -By default, the tag is used as the subject for NATS, so it has to be a valid -subject in case subject it is left unspecified: - -```bash -{% raw %} -$ docker run --log-driver nats \ - --log-opt tag="docker.{{.ID}}.{{.ImageName}}" - your/application -{% endraw %} -``` - -Secure connection to NATS using TLS can be customized by setting `tls://` scheme -in the URI and absolute paths to the certs and key files: - -```bash -docker run --log-driver nats \ - --log-opt nats-tls-key=/srv/configs/certs/client-key.pem \ - --log-opt nats-tls-cert=/srv/configs/certs/client-cert.pem \ - --log-opt nats-tls-ca-cert=/srv/configs/certs/ca.pem \ - --log-opt nats-servers="tls://127.0.0.1:4223,tls://127.0.0.1:4222" \ - your/application -``` - -Skip verify is enabled by default, in order to deactivate we can specify `nats-tls-skip-verify`: - -```bash - docker run --log-driver nats \ - --log-opt nats-tls-skip-verify \ - --log-opt nats-servers="tls://127.0.0.1:4223,tls://127.0.0.1:4222" \ - your/application -``` diff --git a/engine/admin/logging/overview.md b/engine/admin/logging/overview.md index 890939acd2a..42a5e6493bf 100644 --- a/engine/admin/logging/overview.md +++ b/engine/admin/logging/overview.md @@ -69,7 +69,6 @@ for its configurable options, if applicable. | `splunk` | Writes log messages to `splunk` using the HTTP Event Collector.| | `etwlogs` | Writes log messages as Event Tracing for Windows (ETW) events. Only available on Windows platforms. | | `gcplogs` | Writes log messages to Google Cloud Platform (GCP) Logging. | -| `nats` | NATS logging driver for Docker. Publishes log entries to a NATS server.| ## Limitations of logging drivers @@ -124,6 +123,13 @@ This example starts an `alpine` container with the `none` log driver. $ docker run -it --log-driver none alpine ash ``` +### Options for all drivers +| Option | Description | Example value | +|-------------------|-------------|---------------| +| `mode` | Sets the logging mode, accepted values are `blocking` (default), and `non-blocking`. When `non-blocking` is set, if the log buffer fills up, log messages will be lost. How messages are dropped is left undefined. | `--log-opt mode=non-blocking` +| `max-buffer-size` | Applicable only when `mode` is set to `non-blocking`, this sets the maxmimum size of the log buffer. Once this size is reach, log messages will be dropped. | `--log-opt max-buffer-size 5m` + + ## `json-file` `json-file` is the default logging driver, and returns logging output in JSON