Skip to content

Logging technical debt #3615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mdlinville merged 3 commits into from
Jun 20, 2017
Merged

Logging technical debt #3615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2d1f06b
Clarify size and virtual size
Jun 13, 2017
af5eacc
Clarify routing mesh port
Jun 13, 2017
c4de399
Update logging driver options from code
Jun 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 60 additions & 6 deletions engine/admin/logging/awslogs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,25 @@ and Command Line Tools](http://docs.aws.amazon.com/cli/latest/reference/logs/ind

## Usage

You can configure the default logging driver by passing the `--log-driver`
option to the Docker daemon:
To use the `awslogs` driver as the default logging driver, set the `log-driver`
and `log-opt` keys to appropriate values in the `daemon.json` file, which is
located in `/etc/docker/` on Linux hosts or
`C:\ProgramData\docker\config\daemon.json` on Windows Server. For more about
configuring Docker using `daemon.json`, see
[daemon.json](/engine/reference/commandline/dockerd.md#daemon-configuration-file).
The following example sets the log driver to `awslogs` and sets the
`awslogs-region` option.

```json
{
"log-driver": "awslogs",
"log-opts": {
"awslogs-region": "us-east-1"
}
}
```

dockerd --log-driver=awslogs
Restart Docker for the changes to take effect.

You can set the logging driver for a specific container by using the
`--log-driver` option to `docker run`:
Expand All @@ -26,7 +41,9 @@ You can set the logging driver for a specific container by using the

## Amazon CloudWatch Logs options

You can use the `--log-opt NAME=VALUE` flag to specify Amazon CloudWatch Logs logging driver options.
You can add logging options to the `daemon.json` to set Docker-wide defaults,
or use the `--log-opt NAME=VALUE` flag to specify Amazon CloudWatch Logs
logging driver options when starting a container.

### awslogs-region

Expand Down Expand Up @@ -77,6 +94,43 @@ $ docker run --log-driver=awslogs \
> **Note**:
> Your AWS IAM policy must include the `logs:CreateLogGroup` permission before you attempt to use `awslogs-create-group`.

### aws-datetime-format

The `aws-datetime-format` option defines a multiline start pattern in [Python
`strftime` format](http://strftime.org). One example of a use case for using
this format is for parsing output such as a stack dump, which might otherwise
be logged in multiple entries. The correct pattern allows it to be captured in a
single entry.

This option always takes precedence if both `awslogs-datetime-format` and
`awslogs-multiline-pattern` are configured.

For example:

```bash
$ docker run -it --rm \
--log-driver=awslogs \
--log-opt awslogs-group=test \
--log-opt awslogs-datetime-format='%Y-%m-%d' \
awslogtest:latest /test2.sh
```

### aws-multiline-pattern

The `aws-multiline-pattern` option defines a multiline start pattern using a
regular expression. This option is ignored if `awslogs-datetime-format` is also
configured.
Copy link
Copy Markdown
Member

@thaJeztah thaJeztah Jun 15, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should mention what this is useful for, or do you think it's clear from this? (usage can be an application that outputs, e.g. a stack-dump, which would otherwise be logged in multiple entries, and now allows you to capture it in a single log-entry. (could be better examples though)

Copy link
Copy Markdown
Author

@mdlinville mdlinville Jun 19, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


For example:

```bash
$ docker run -it --rm \
--log-driver=awslogs \
--log-opt awslogs-group=test \
--log-opt awslogs-multiline-pattern='^ABCD' \
awslogtest:latest /test1.sh

```

### tag

Expand All @@ -90,9 +144,9 @@ If not specified, the container ID is used as the log stream.
{% raw %}
> **Note**:
> The CloudWatch log API doesn't support `:` in the log name. This can cause some issues when using the `{{ .ImageName }}` as a tag, since a docker image has a format of `IMAGE:TAG`, such as `alpine:latest`.
> Template markup can be used to get the proper format.
> Template markup can be used to get the proper format.
> To get the image name and the first 12 characters of the container id, you can use: `--log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}'`
> the output will be something like: `alpine_latest-bf0072049c76`
> the output will be something like: `alpine_latest-bf0072049c76`
{% endraw %}


Expand Down
59 changes: 48 additions & 11 deletions engine/admin/logging/fluentd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,11 @@ destinations.
In addition to the log message itself, the `fluentd` log
driver sends the following metadata in the structured log message:

| Field | Description |
-------------------|-------------------------------------|
| `container_id` | 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. |
| `source` | `stdout` or `stderr` |
| Field | Description |
|:-----------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `container_id` | 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. |
| `source` | `stdout` or `stderr` |

The `docker logs` command is not available for this logging driver.

Expand All @@ -32,10 +32,26 @@ Some options are supported by specifying `--log-opt` as many times as needed:
- `tag`: specify tag for fluentd message, which interpret some markup, ex {% raw %}`{{.ID}}`, `{{.FullID}}` or `{{.Name}}` `docker.{{.ID}}`{% endraw %}


Configure the default logging driver by passing the
`--log-driver` option to the Docker daemon:
To use the `fluentd` driver as the default logging driver, set the `log-driver`
and `log-opt` keys to appropriate values in the `daemon.json` file, which is
located in `/etc/docker/` on Linux hosts or
`C:\ProgramData\docker\config\daemon.json` on Windows Server. For more about
+configuring Docker using `daemon.json`, see
+[daemon.json](/engine/reference/commandline/dockerd.md#daemon-configuration-file).

dockerd --log-driver=fluentd
The following example sets the log driver to `fluentd` and sets the
`fluentd-address` option.

```json
{
"log-driver": "fluentd",
"log-opts": {
"fluentd-address": "fluentdhost:24224"
}
}
```

Restart Docker for the changes to take effect.

To set the logging driver for a specific container, pass the
`--log-driver` option to `docker run`:
Expand Down Expand Up @@ -73,13 +89,34 @@ Refer to the [log tag option documentation](log_tags.md) for customizing
the log tag format.


### labels and env
### labels, env, and env-regex

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 fields to the extra attributes of a
logging message.

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 fields to the extra attributes of a logging message.
The `env-regex` option is similar to and compatible with `env`. Its value is a
regular expression to match logging-related environment variables. It is used
for advanced [log tag options](log_tags.md).

### fluentd-async-connect

Docker connects to Fluentd in the background. Messages are buffered until the connection is established.
Docker connects to Fluentd in the background. Messages are buffered until the
connection is established.

### fluentd-buffer-limit

The amount of data to buffer before flushing to disk. Defaults the amount of RAM
available to the container.

### fluentd-retry-wait

How long to wait between retries. Defaults to 1 second.

### fluentd-max-retries

The maximum number of retries. Defaults to 10.

## Fluentd daemon management with Docker

Expand Down
63 changes: 40 additions & 23 deletions engine/admin/logging/gcplogs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,32 @@ keywords: gcplogs, google, docker, logging, driver
title: Google Cloud Logging driver
---

The Google Cloud Logging driver sends container logs to <a
href="https://cloud.google.com/logging/docs/" target="_blank">Google Cloud
Logging</a>.
The Google Cloud Logging driver sends container logs to
[Google Cloud Logging](https://cloud.google.com/logging/docs/){: target="_blank" class="_" }
Logging.

## Usage

You can configure the default logging driver by passing the `--log-driver`
option to the Docker daemon:
To use the `gcplogs` driver as the default logging driver, set the `log-driver`
and `log-opt` keys to appropriate values in the `daemon.json` file, which is
located in `/etc/docker/` on Linux hosts or
`C:\ProgramData\docker\config\daemon.json` on Windows Server. For more about
configuring Docker using `daemon.json`, see
[daemon.json](/engine/reference/commandline/dockerd.md#daemon-configuration-file).

dockerd --log-driver=gcplogs
The following example sets the log driver to `gcplogs` and sets the
`gcp-meta-name` option.

```json
{
"log-driver": "gcplogs",
"log-opts": {
"gcp-meta-name": "example-instance-12345"
}
}
```

Restart Docker for the changes to take effect.

You can set the logging driver for a specific container by using the
`--log-driver` option to `docker run`:
Expand All @@ -24,15 +40,15 @@ This log driver does not implement a reader so it is incompatible with
`docker logs`.

If Docker detects that it is running in a Google Cloud Project, it will discover
configuration from the <a href="https://cloud.google.com/compute/docs/metadata"
target="_blank">instance metadata service</a>. Otherwise, the user must specify
configuration from the
[instance metadata service](https://cloud.google.com/compute/docs/metadata){: target="_blank" class="_"}
Otherwise, the user must specify
which project to log to using the `--gcp-project` log option and Docker will
attempt to obtain credentials from the <a
href="https://developers.google.com/identity/protocols/application-default-credentials"
target="_blank">Google Application Default Credential</a>. The `--gcp-project`
takes precedence over information discovered from the metadata server so a
Docker daemon running in a Google Cloud Project can be overridden to log to a
different Google Cloud Project using `--gcp-project`.
attempt to obtain credentials from the
[Google Application Default Credential](https://developers.google.com/identity/protocols/application-default-credentials){: target="_blank" class="_"}.
The `--gcp-project` flag takes precedence over information discovered from the
metadata server so a Docker daemon running in a Google Cloud Project can be
overridden to log to a different Google Cloud Project using `--gcp-project`.

Docker fetches the values for zone, instance name and instance id from Google
Cloud metadata server. Those values can be provided via options if metadata
Expand All @@ -43,15 +59,16 @@ server is not available. They will not override the values from metadata server.
You can use the `--log-opt NAME=VALUE` flag to specify these additional Google
Cloud Logging driver options:

| Option | Required | Description |
|-----------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `gcp-project` | optional | Which GCP project to log to. Defaults to discovering this value from the GCE metadata service. |
| `gcp-log-cmd` | optional | Whether to log the command that the container was started with. Defaults to false. |
| `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. |
| `gcp-meta-zone` | optional | Zone name for the instance. |
| `gcp-meta-name` | optional | Instance name. |
| `gcp-meta-id` | optional | Instance ID. |
| Option | Required | Description |
|:----------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `gcp-project` | optional | Which GCP project to log to. Defaults to discovering this value from the GCE metadata service. |
| `gcp-log-cmd` | optional | Whether to log the command that the container was started with. Defaults to false. |
| `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. |
| `env-regex` | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](log_tags.md). |
| `gcp-meta-zone` | optional | Zone name for the instance. |
| `gcp-meta-name` | optional | Instance name. |
| `gcp-meta-id` | optional | Instance ID. |

If there is collision between `label` and `env` keys, the value of the `env`
takes precedence. Both options add additional fields to the attributes of a
Expand Down
38 changes: 29 additions & 9 deletions engine/admin/logging/gelf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,26 @@ In GELF, every log message is a dict with the following fields:

## Usage

To use the `gelf` driver as the default logging driver, set the `log-driver` and
`log-opt` keys to appropriate values in the `daemon.json` file, which is located
in `/etc/docker/` on Linux hosts or `C:\ProgramData\docker\config\daemon.json`
on Windows Server. For more about configuring Docker using `daemon.json`, see
[daemon.json](/engine/reference/commandline/dockerd.md#daemon-configuration-file).

The following example sets the log driver to `gelf` and sets the `gelf-address`
option.

```json
{
"log-driver": "gelf",
"log-opts": {
"gelf-address": "udp://1.2.3.4:12201"
}
}
```

Restart Docker for the changes to take effect.

To use `gelf` as the default logging driver for new containers, pass the `--log-driver`
and `--log-opt` options to the Docker daemon:

Expand Down Expand Up @@ -52,15 +72,15 @@ $ docker run \

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` |

| 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. Either `-1` or `0` disables compression. | `--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` | 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

Expand Down
Loading