From d88478a722e51c539c809a0bc120811e9eb1b001 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Thu, 1 Jun 2017 13:43:11 -0700 Subject: [PATCH] Document logging driver plugins (#3440) --- _data/toc.yaml | 2 + engine/admin/logging/index.md | 19 -- engine/admin/logging/overview.md | 462 ++++++------------------------- engine/admin/logging/plugins.md | 43 +++ 4 files changed, 122 insertions(+), 404 deletions(-) delete mode 100644 engine/admin/logging/index.md create mode 100644 engine/admin/logging/plugins.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 6fe7cbe894..38b52ac69f 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -245,6 +245,8 @@ guides: title: View a container's logs - path: /engine/admin/logging/overview/ title: Configuring logging drivers + - path: /engine/admin/logging/plugins/ + title: Use a logging driver plugin - path: /engine/admin/logging/log_tags/ title: Log tags for logging driver - path: /engine/admin/logging/logentries/ diff --git a/engine/admin/logging/index.md b/engine/admin/logging/index.md deleted file mode 100644 index 063d4f838d..0000000000 --- a/engine/admin/logging/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -description: Logging and Logging Drivers -keywords: ' docker, logging, driver' -redirect_from: -- /engine/reference/logging/ -title: Logging drivers ---- - -* [Configuring logging drivers](overview.md) -* [Configuring log tags](log_tags.md) -* [JSON File logging driver](json-file.md) -* [Fluentd logging driver](fluentd.md) -* [Journald logging driver](journald.md) -* [Syslog logging driver](syslog.md) -* [Graylog Extended Format logging driver](gelf.md) -* [Amazon CloudWatch Logs logging driver](awslogs.md) -* [Splunk logging driver](splunk.md) -* [ETW logging driver](etwlogs.md) -* [Google Cloud Logging driver](gcplogs.md) diff --git a/engine/admin/logging/overview.md b/engine/admin/logging/overview.md index 8d3ad87c5c..bba39e0776 100644 --- a/engine/admin/logging/overview.md +++ b/engine/admin/logging/overview.md @@ -3,6 +3,8 @@ description: Configure logging driver. keywords: docker, logging, driver redirect_from: - /engine/reference/logging/overview/ +- /engine/reference/logging/ +- /engine/admin/reference/logging/ title: Configure logging drivers --- @@ -13,19 +15,48 @@ drivers. Each Docker daemon has a default logging driver, which each container uses unless you configure it to use a different logging driver. -## Configure the default logging driver for the Docker daemon +In addition to using the logging drivers included with Docker, you can also +implement and use [logging driver plugins](/engine/admin/reference/logging/plugins.md). +Logging driver plugins are available in Docker 17.05 and higher. + +{% include edge_only.md section="feature" %} + +## Configure the default logging driver + +To configure the Docker daemon to default to a specific logging driver, set the +value of `log-driver` to the name of the logging driver in the `daemon.json` +file, which is located in `/etc/docker/` on Linux hosts or +`C:\ProgramData\docker\config\` on Windows server hosts. The default logging +driver is `json-file`. The following example explicitly sets the default +logging driver to `syslog`: + +```json +{ + "log-driver": "syslog" +} +``` + +If the logging driver has configurable options, you can set them in the +`daemon.json` file as a JSON array with the key `log-opts`. The following +example sets two configurable options on the `json-file` logging driver: + +```json +{ + "log-driver": "json-file", + "log-opts": [ + "labels=production_status", + "env=os,customer" + ] +} +``` -To configure the Docker daemon to default to a specific logging driver, use the -`--log-driver=` flag. If the logging driver has configurable options, -you can set them using one or more instances of the `--log-opt =` -flag. If you do not specify a logging driver, the default is `json-file`. Thus, the default output for commands such as `docker inspect ` is JSON. To find the current default logging driver for the Docker daemon, run `docker info` and search for `Logging Driver`. You can use the following -command on Linux or macOS: +command on Linux, macOS, or PowerShell on Windows: ```bash $ docker info |grep 'Logging Driver' @@ -36,10 +67,16 @@ Logging Driver: json-file ## Configure the logging driver for a container When you start a container, you can configure it to use a different logging -driver than the Docker daemon's default. If the logging driver has configurable -options, you can set them using one or more instances of the -`--log-opt =` flag. Even if the container uses the default logging -driver, it can use different configurable options. +driver than the Docker daemon's default, using the `--log-driver` flag. If the +logging driver has configurable options, you can set them using one or more +instances of the `--log-opt =` flag. Even if the container uses the +default logging driver, it can use different configurable options. + +The following example starts an Alpine container with the `none` logging driver. + +```bash +$ docker run -it --log-driver none alpine ash +``` To find the current logging driver for a running container, if the daemon is using the `json-file` logging driver, run the following `docker inspect` @@ -53,391 +90,46 @@ json-file {% endraw %} ``` -## Supported logging drivers +### Use environment variables or labels with logging drivers -The following logging drivers are supported. See each driver's section below -for its configurable options, if applicable. - -| Driver | Description | -|-------------|----------------------------------------------------------------| -| `none` | No logs will be available for the container and `docker logs` will not return any output. | -| `json-file` | The logs are formatted as JSON. The default logging driver for Docker. | -| `syslog` | Writes logging messages to the `syslog` facility. The `syslog` daemon must be running on the host machine. | -| `journald` | Writes log messages to `journald`. The `journald` daemon must be running on the host machine. | -| `gelf` | Writes log messages to a Graylog Extended Log Format (GELF) endpoint such as Graylog or Logstash. | -| `fluentd` | Writes log messages to `fluentd` (forward input). The `fluentd` daemon must be running on the host machine. | | -| `awslogs` | Writes log messages to Amazon CloudWatch Logs. | -| `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. | - -## 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 - -If your container uses labels or environment variables specified in the -Dockerfile or at runtime, some logging drivers can use these labels or -environment variables to control logging behavior. If a collision occurs -between a label and an environment variable, the environment variable takes -precedence. - -Specify logging attributes and options when you start the Docker daemon. For -example, to manually start the daemon with the `json-file` driver, and set a -label and two environment variables, use the following command: - -```bash -$ dockerd \ - --log-driver=json-file \ - --log-opt labels=production_status \ - --log-opt env=os,customer -``` - -Next, run a container and specify values for the `labels` or `env`. For -example, you might use this: +Some logging drivers add the value of a container's `--env|-e` or `--label` +flags to the container's logs. This example starts a container using the Docker +daemon's default logging driver (let's assume `json-file`) but sets the +environment variable `os=ubuntu`. ```bash $ docker run -dit --label production_status=testing -e os=ubuntu alpine sh ``` If the logging driver supports it, this adds additional fields to the logging -output. The following output is for `json-file`: +output. The following output is generated by the `json-file` logging driver: ```json "attrs":{"production_status":"testing","os":"ubuntu"} ``` -## `none` +## Supported logging drivers + +The following logging drivers are supported. See the link to each driver's +documentation for its configurable options, if applicable. If you are using +[logging driver plugins](/engine/admin/reference/logging/plugins.md), you may +see more options. + +| Driver | Description | +|:----------------------------|:--------------------------------------------------------------------------------------------------------------| +| `none` | No logs will be available for the container and `docker logs` will not return any output. | +| [`json-file`](json-file.md) | The logs are formatted as JSON. The default logging driver for Docker. | +| [`syslog`](syslog.md) | Writes logging messages to the `syslog` facility. The `syslog` daemon must be running on the host machine. | +| [`journald`](journald.md) | Writes log messages to `journald`. The `journald` daemon must be running on the host machine. | +| [`gelf`](gelf.md) | Writes log messages to a Graylog Extended Log Format (GELF) endpoint such as Graylog or Logstash. | +| [`fluentd`](fluentd.md) | Writes log messages to `fluentd` (forward input). The `fluentd` daemon must be running on the host machine. | | +| [`awslogs`](awslogs.md) | Writes log messages to Amazon CloudWatch Logs. | +| [`splunk`](splunk.md) | Writes log messages to `splunk` using the HTTP Event Collector. | +| [`etwlogs`](etwlogs.md) | Writes log messages as Event Tracing for Windows (ETW) events. Only available on Windows platforms. | +| [`gcplogs`](gcplogs.md) | Writes log messages to Google Cloud Platform (GCP) Logging. | + +## Limitations of logging drivers + +The `docker logs` command is not available for drivers other than `json-file` +and `journald`. -The `none` driver disables logging for the Docker daemon (if set on the daemon -at start-up) or for an individual container at runtime. It has no options. - -### Examples - -This example starts an `alpine` container with the `none` log driver. - -```bash -$ docker run -it --log-driver none alpine ash -``` - -### Options for all drivers - -{% include edge_only.md section="options" %} - -| 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 reached, 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 -format. For detailed information on working with this logging driver, see [the json-file](json-file.md) reference documentation. - -### Options - -The `json-file` logging driver supports the following logging options: - -| Option | Description | Example value | -|------------|--------------------------|-------------------------------------------| -| `max-size` | The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). | `--log-opt max-size=10m` | -| `max-file` | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. **Only effective when `max-size` is also set.** A positive integer. | `--log-opt max-file=3` | -| `labels` | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon will accept. 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. Used for advanced [log tag options](log_tags.md). | `--log-opt env=os,customer` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - -> **Note**: If `max-size` and `max-file` are set, `docker logs` only returns the -> log lines from the newest log file. - -### Examples - -This example starts an `alpine` container which can have a maximum of 3 log -files no larger than 10 megabytes each. - -```bash -$ docker run -it --log-opt max-size=10m --log-opt max-file=3 alpine ash -``` - -## `syslog` - -The `syslog` logging driver routes logs to a `syslog` server. -For detailed information on working with this logging driver, see [the syslog logging driver](syslog.md) reference documentation. - -### Options - -The following logging options are supported for the `syslog` logging driver: - -| Option | Description | Example value | -|----------------------|--------------------------|-------------------------------------------| -| `syslog-address` | The address of an external `syslog` server. The URI specifier may be `[tcp|udp|tcp+tls]://host:port`, `unix://path`, or `unixgram://path`. If the transport is `tcp`, `udp`, or `tcp+tls`, the default port is `514`.| `--log-opt syslog-address=tcp+tls://192.168.1.3:514`, `--log-opt syslog-address=unix:///tmp/syslog.sock` | -| `syslog-facility` | The `syslog` facility to use. Can be the number or name for any valid `syslog` facility. See the [syslog documentation](https://tools.ietf.org/html/rfc5424#section-6.2.1). | `--log-opt syslog-facility=daemon` | -| `syslog-tls-ca-cert` | The absolute path to the trust certificates signed by the CA. **Ignored if the address protocol is not `tcp+tls`.** | `--log-opt syslog-tls-ca-cert=/etc/ca-certificates/custom/ca.pem` | -| `syslog-tls-cert` | The absolute path to the TLS certificate file. **Ignored if the address protocol is not `tcp+tls`**. | `--log-opt syslog-tls-cert=/etc/ca-certificates/custom/cert.pem` | -| `syslog-tls-key` | The absolute path to the TLS key file. **Ignored if the address protocol is not `tcp+tls`.** | `--log-opt syslog-tls-key=/etc/ca-certificates/custom/key.pem` | -| `syslog-tls-skip` | If set to `true`, TLS verification is skipped when connecting to the `syslog` daemon. Defaults to `false`. **Ignored if the address protocol is not `tcp+tls`.** | `--log-opt syslog-tls-skip-verify=true` | -| `tag` | A string that is appended to the `APP-NAME` in the `syslog` message. By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. | `--log-opt tag=mailer` | -| `syslog-format` | The `syslog` message format to use. If not specified the local UNIX syslog format is used, without a specified hostname. Specify `rfc3164` for the RFC-3164 compatible format, `rfc5424` for RFC-5424 compatible format, or `rfc5424micro` for RFC-5424 compatible format with microsecond timestamp resolution. | `--log-opt syslog-format=rfc5424micro` | -| `labels` | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon will accept. 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. Used for advanced [log tag options](log_tags.md). | `--log-opt env=os,customer` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - -### Examples - -This example sends the container's logging output to a `syslog` remote server at -`192.168.0.42` on port `123`, using the the `daemon` facility: - -```bash -$ docker run \ - --log-driver=syslog \ - --log-opt syslog-address=tcp://192.168.0.42:123 \ - --log-opt syslog-facility=daemon \ - alpine ash -``` - -This example connects to `syslog` using TCP+TLS transport and specifies the -trust certificate, certificate, and key to use. - -```bash -$ docker run \ - --log-driver=syslog \ - --log-opt syslog-address=tcp+tls://192.168.0.42:123 \ - --log-opt syslog-tls-ca-cert=/etc/ca-certificates/custom/ca.pem \ - --log-opt syslog-tls-cert=/etc/ca-certificates/custom/cert.pem \ - --log-opt syslog-tls-key=/etc/ca-certificates/custom/key.pem \ - alpine ash -``` - -## `journald` - -The `journald` logging driver stores the container id in the journal's -`CONTAINER_ID` field. For detailed information on working with this logging -driver, see [the journald logging driver](journald.md) reference documentation. - -### Options - -| Option | Description | Example value | -|------------|--------------------------|-------------------------------------------| -| `tag` | A template for setting the `CONTAINER_TAG` value in `journald` logs. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. | `--log-opt tag=mailer` | -| `labels` | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon will accept. 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. Used for advanced [log tag options](log_tags.md). | `--log-opt env=os,customer` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - - -### Examples - -```bash -$ docker run \ - --log-driver=journald \ - alpine ash -``` - -## `gelf` - -The `gelf` logging driver is a convenient format that is understood by a number of tools like [Graylog](https://www.graylog.org/), [Logstash](https://www.elastic.co/products/logstash), [Fluentd](http://www.fluentd.org/), and many more. For detailed information on working with this logging driver, see [the Graylog Extended Format logging driver](gelf.md) reference documentation. - -### Options - -The `gelf` logging driver supports the following options: - -| Option | Description | Example value | -|----------------------|--------------------------|-------------------------------------------| -| `gelf-address` | The address of the GELF server. `udp` is the only supported URI specifier and you must specify the port.| `--log-opt gelf-address=udp://192.168.0.42:12201` | -| `gelf-compression-type` | The type of compression the GELF driver uses to compress each log message. Allowed values are `gzip`, `zlib` and `none`. The default is `gzip`. | `--log-opt gelf-compression-type=gzip` | -| `gelf-compression-level` | The level of compression when `gzip` or `zlib` is the `gelf-compression-type`. An integer in the range of `-1` to `9` (BestCompression). Default value is 1 (BestSpeed). Higher levels provide more compression at lower speed.| `--log-opt gelf-compression-level=2` | -| `tag` | A string that is appended to the `APP-NAME` in the `gelf` message. By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. | `--log-opt tag=mailer` | -| `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` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - - -### Examples - -This example connects the container to the GELF server running at -`192.168.0.42` on port `12201`. - -```bash -$ docker run -dit \ - --log-driver=gelf \ - --log-opt gelf-address=udp://192.168.0.42:12201 \ - alpine sh -``` - - -## `fluentd` - -### Options - -The `fluentd` logging driver supports the following options: - -| Option | Description | Example value | -|------------------------|--------------------------|-------------------------------------------| -| `fluentd-address` | The address of the Fluentd server, in the format `host:port` with no protocol specifier.| `--log-opt fluentd-address=192.168.0.42:24224` | -| `fluentd-buffer-limit` | The maximum size of the fluentd log buffer, with a size prefix `KB`, `MB`, or `GB`. Defaults to `8MB`. | `--log-opt fluentd-buffer-limit=8MB` | -| `fluentd-retry-wait` | The initial delay before retrying after a connection failure. After the initial delay, it increases exponentially. Defaults to `1000ms`.| `--log-opt fluentd-retry-wait=1000ms` | -| `fluentd-max-retries` | The maximum number of connection attempts before the container stops due to failure to connect. Defaults to `1073741824`, which is effectively infinite. | `--log-opt fluentd-max-retries=200` | -| `fluentd-async-connect`| If set to `false`, Docker blocks on initial connection and the container stops if it cannot connect. Defaults to `false`. | `--log-opt fluentd-async-connect=false` | -| `tag` | A string that is appended to the `APP-NAME` in the `fluentd` message. By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](log_tags.md) for customizing the log tag format. | `--log-opt tag=mailer` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - -### Examples - -This example logs container output to the Fluentd server running on `localhost` -at port `24224` and prepends the tag `docker.` to the beginning -of each message. - -```bash -{% raw %} -$ docker run -dit \ - --log-driver=fluentd \ - --log-opt fluentd-address=localhost:24224 \ - --log-opt tag="docker.{{.Name}}" \ - alpine sh -{% endraw %} -``` - -For detailed information on working with the `fluentd` logging driver, see -[the fluentd logging driver](fluentd.md). - - -## `awslogs` - -The Amazon Cloudwatch Logs driver is called `awslogs`. - -### Options - -The `awslogs` supports the following options: - -| Option | Description | Example value | -|------------------------|--------------------------|-------------------------------------------| -| `awslogs-region` | Sets the region where the logs are sent. If not set, the container's region is used. | `--log-opt awslogs-region=us-east-1` | -| `awslogs-group` | The log group to use for the logs. | `--log-opt awslogs-group=myLogGroup` | -| `awslogs-stream` | The log stream to use. If not specified, the container ID is used as the log stream. | `--log-opt awslogs-stream=myLogStream` | -| `awslogs-create-group` | If the option is set to true, create the log group if the log group does not exist yet. | `--log-opt awslogs-create-group=true` | - -### Examples - -This example sends the logs to region `us-east-1` and uses the log group -`myLogGroup`. - -```bash -$ docker run \ - --log-driver=awslogs \ - --log-opt awslogs-region=us-east-1 \ - --log-opt awslogs-group=myLogGroup \ - --log-opt awslogs-create-group=true \ - alpine sh -``` - -For detailed information on working with this logging driver, see -[the `awslogs` logging driver](awslogs.md) reference documentation. - -## `splunk` - -The `splunk` logging driver sends container logs to the -[HTTP Event Collector](http://dev.splunk.com/view/event-collector/SP-CAAAE6M) -in Splunk Enterprise and Splunk Cloud. - -### Options - -The `splunk` logging driver **requires** the following options: - -| Option | Description | Example value | -|------------------------|--------------------------|-------------------------------------------| -| `splunk-token` | The Splunk HTTP Event Collector token. | `--log-opt splunk-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 | -|------------------------|---------------------------------|-------------------------------------------| -| `splunk-source` | Event source. | `--log-opt splunk-source=prod` | -| `splunk-sourcetype` | Event source type. | `--log-opt splunk-sourcetype=iis` | -| `splunk-index` | Event index. | `--log-opt splunk-index=os` | -| `splunk-capath` | Path to root certificate. | `--log-opt splunk-capath=/path/to/cert/cacert.pem` | -| `splunk-caname` | Name to use for validating server certificate. Defaults to the hostname of the `splunk-url`. | `--log-opt splunk-caname=SplunkServerDefaultCert` | -| `splunk-insecureskipverify` | Ignore server certificate validation. | `--log-opt splunk-insecureskipverify=false` | -| `tag` | Specify tag for message, which interpret some markup. Default value is {% raw %}`{{.ID}}`{% endraw %} (12 characters of the container ID). Refer to the [log tag option documentation](log_tags.md) for information about customizing the log tag format. | {% raw %}`--log-opt tag="{{.Name}}/{{.FullID}}"`{% endraw %} | -| `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` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - - -### Examples - -This examples sets several options for the `splunk` logging driver. - -```bash -{% raw %} -$ docker run \ - --log-driver=splunk \ - --log-opt splunk-token=176FCEBF-4CF5-4EDF-91BC-703796522D20 \ - --log-opt splunk-url=https://splunkhost:8088 \ - --log-opt splunk-capath=/path/to/cert/cacert.pem \ - --log-opt splunk-caname=SplunkServerDefaultCert \ - --log-opt tag="{{.Name}}/{{.FullID}}" \ - --log-opt labels=location \ - --log-opt env=TEST \ - --env "TEST=false" \ - --label location=west \ - alpine sh -{% endraw %} -``` - -For detailed information about working with the `splunk` logging driver, see the -[Splunk logging driver](splunk.md) reference documentation. - -## `etwlogs` - -### Options - -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 - -```bash -$ docker run \ - --logging-driver=etwlogs \ - alpine sh -``` - -The ETW logging driver is only available on Windows. For detailed information -about working with this logging driver, see [the ETW logging driver](etwlogs.md) -reference documentation. - -## `gcplogs` - -### Options - -The Google Cloud Platform logging driver (`gcplogs`) supports the following -options: - -| Option | Description | Example value | -|------------------------|---------------------------------|-------------------------------------------| -| `gcp-project` | The GCP project to log to. Defaults to discovering this value from the GCE metadata service. | `--log-opt gcp-project=myProject` | -| `log-cmd` | | `--log-opt log-cmd=true` | Whether to log the command that started the container. Defaults to `false`. | `--log-opt log-cmd=false` | -| `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` | -| `env-regex`| Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). | `--log-opt env-regex=^(os|customer)` | - -### Examples - -This example logs the start command and sets a label and an environment -variable, which will be incorporated into the logs if the Docker daemon was -started with the appropriate `--log-opt` options. - -```bash -$ docker run --log-driver=gcplogs \ - --log-opt gcp-log-cmd=true \ - --env "TEST=false" \ - --label location=west \ - your/application \ -``` - -For detailed information about working with the Google Cloud logging driver, see -the [Google Cloud Logging driver](gcplogs.md) reference documentation. diff --git a/engine/admin/logging/plugins.md b/engine/admin/logging/plugins.md new file mode 100644 index 0000000000..d8695aeb82 --- /dev/null +++ b/engine/admin/logging/plugins.md @@ -0,0 +1,43 @@ +--- +description: How to use logging driver plugins +title: Use a logging driver plugin +keywords: logging, driver, plugins, monitoring +--- + +{% include edge_only.md section="page" %} + +Docker logging plugins allow you to extend and customize Docker's logging +capabilities beyond those of the [built-in logging drivers](overview.md). +A logging service provider can +[implement their own plugins](/engine/extend/plugins_logging.md) and make them +available on Docker Hub, Docker Store, or a private registry. This topic shows +how a user of that logging service can configure Docker to use the plugin. + +## Install the logging driver plugin + +To install a logging driver plugin, use `docker plugin install `, +using the information provided by the plugin developer. + +You can list all installed plugins using `docker plugin ls`, and you can inspect +a specific plugin using `docker inspect`. + +## Configure the plugin as the default logging driver + +After the plugin is installed, you can configure the Docker daemon to use it as +the default by setting the plugin's name as the value of the `logging-driver` +key in the `daemon.json`, as detailed in the +[logging overview](overview.md#configure-the-default-logging-driver). If the +logging driver supports additional options, you can set those as the values of +the `log-opts` array in the same file. + +## Configure a container to use the plugin as the logging driver + +After the plugin is installed, you can configure a container to use the plugin +as its logging driver by specifying the `--log-driver` flag to `docker run`, as +detailed in the +[logging overview](overview.md#configure-the-logging-driver-for-a-container). +If the logging driver supports additional options, you an specify them using +one or more `--log-opt` flags with the option name as the key and the option +value as the value. + +