Add NATS client as option for publishing container logs (#369)

* Add NATS client as option for publishing container logs

Signed-off-by: Waldemar Quevedo <waldemar.quevedo@gmail.com>
This commit is contained in:
Waldemar Quevedo 2016-11-22 15:07:29 -08:00 committed by Misty Stanley-Jones
parent 4b631d8025
commit 9e20d71853
3 changed files with 122 additions and 19 deletions

View File

@ -13,4 +13,5 @@ title: Logging drivers
* [Amazon CloudWatch Logs logging driver](awslogs.md)
* [Splunk logging driver](splunk.md)
* [ETW logging driver](etwlogs.md)
* [Google Cloud Logging driver](gcplogs.md)
* [Google Cloud Logging driver](gcplogs.md)
* [NATS Logging driver](nats.md)

View File

@ -0,0 +1,88 @@
---
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
```

View File

@ -67,14 +67,13 @@ 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
- The `docker logs` command is not available for drivers other than `json-file`
and `journald`.
-
## Examples
### Configure the logging driver using labels or environment variables
@ -250,10 +249,7 @@ $ docker run -dit \
## `fluentd`
The `gelf-compression-level` option can be used to change the level of
compresssion when `gzip` or `zlib` is selected as `gelf-compression-type`.
Accepted value must be from -1 to 9 (BestCompression). Higher levels
typically run slower but compress more. Default value is 1 (BestSpeed).
### Options
The `fluentd` logging driver supports the following options:
@ -275,10 +271,10 @@ of each message.
```bash
{% raw %}
$ docker run -dit \
--log-driver=fluentd \
--log-opt fluentd-address=localhost:24224 \
--log-opt tag="docker.{{.Name}}" \
alpine sh
--log-driver=fluentd \
--log-opt fluentd-address=localhost:24224 \
--log-opt tag="docker.{{.Name}}" \
alpine sh
{% endraw %}
```
@ -331,7 +327,6 @@ The `splunk` logging driver **requires** the following options:
| `splunk-token` | The Splunk HTTP Event Collector token. | `--log-opt splunk-token=<splunk_http_event_collector_token>` |
| `splunk-url` | Path to your Splunk Enterprise or Splunk Cloud instance (including port and scheme used by HTTP Event Collector).| `--log-opt splunk-url=https://your_splunk_instance:8088` |
The `splunk` logging driver **allows** the following options:
| Option | Description | Example value |
@ -375,9 +370,9 @@ For detailed information about working with the `splunk` logging driver, see the
### Options
The etwlogs logging driver does not require any options to be specified. This
logging driver forwards each log message as an ETW event. An ETW listener
can then be created to listen for these events.
The `etwlogs` logging driver forwards each log message as an ETW event. An ETW
listener can then be created to listen for these events. This driver does not
accept any options.
### Examples
@ -388,7 +383,7 @@ $ docker run \
```
The ETW logging driver is only available on Windows. For detailed information
on working with this logging driver, see [the ETW logging driver](etwlogs.md)
about working with this logging driver, see [the ETW logging driver](etwlogs.md)
reference documentation.
## `gcplogs`
@ -405,7 +400,6 @@ options:
| `labels` | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon will accept. Adds additional key on the `extra` fields, prefixed by an underscore (`_`). Used for advanced [log tag options](log_tags.md).| `--log-opt labels=production_status,geo` |
| `env` | Applies when starting the Docker daemon. A comma-separated list of logging-related environment variables this daemon will accept. Adds additional key on the `extra` fields, prefixed by an underscore (`_`). Used for advanced [log tag options](log_tags.md). | `--log-opt env=os,customer` |
### Examples
This example logs the start command and sets a label and an environment
@ -420,5 +414,25 @@ $ docker run --log-driver=gcplogs \
your/application \
```
For detailed information about working with this logging driver, see the
[Google Cloud Logging driver](gcplogs.md). reference documentation.
For detailed information about working with the Google Cloud logging driver, see
the [Google Cloud Logging driver](gcplogs.md). reference documentation.
## NATS logging options
The NATS logging driver supports the following options:
```none
--log-opt labels=<label1>,<label2>
--log-opt env=<envvar1>,<envvar2>
--log-opt tag=<tag>
--log-opt nats-servers="<comma separated list of nats servers uris>"
--log-opt nats-max-reconnect="<max attempts to connect to a server>"
--log-opt nats-subject="<subject where logs are sent>"
--log-opt nats-tls-ca-cert="<absolute path to cert>"
--log-opt nats-tls-cert="<absolute path to cert>"
--log-opt nats-tls-key="<absolute path to cert>"
--log-opt nats-tls-skip-verify="<value>"
```
For detailed information, see [the NATS logging driver](nats.md) reference
documentation.