Amazon CloudWatch Logs 日志记录驱动程序

awslogs 日志驱动将容器日志发送到 Amazon CloudWatch Logs。 日志条目可以通过 AWS 管理 控制台 或 AWS SDK 和命令行工具 检索。

用法

要将 awslogs 驱动程序用作默认日志驱动程序，请在 daemon.json 文件中设置 log-driver 和 log-opt 键为适当的值，该文件位于 Linux 主机上的 /etc/docker/ 或 Windows Server 上的 C:\ProgramData\docker\config\daemon.json。有关使用 daemon.json 配置 Docker 的更多信息，请参阅 daemon.json。 以下示例将日志驱动程序设置为 awslogs 并设置 awslogs-region 选项。

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

重启 Docker 以使更改生效。

您可以通过使用 --log-driver 选项为 docker run 设置特定容器的日志驱动：

$ docker run --log-driver=awslogs ...

如果您正在使用 Docker Compose，请使用以下声明示例将 awslogs 设置为：

myservice:
  logging:
    driver: awslogs
    options:
      awslogs-region: us-east-1

Amazon CloudWatch Logs 选项

您可以将日志选项添加到 daemon.json 以设置 Docker 范围内的默认值， 或在启动容器时使用 --log-opt NAME=VALUE 标志指定 Amazon CloudWatch Logs 日志驱动程序选项。

awslogs-region

awslogs 日志驱动程序将您的 Docker 日志发送到特定区域。使用 awslogs-region 日志选项或 AWS_REGION 环境变量来设置 区域。默认情况下，如果您的 Docker 守护进程在 EC2 实例上运行 且未设置区域，则该驱动程序使用实例的区域。

$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 ...

awslogs-endpoint

默认情况下，Docker 使用 awslogs-region 日志选项或检测到的区域来构建远程 CloudWatch Logs API 端点。 使用 awslogs-endpoint 日志选项可以用提供的端点覆盖默认端点。

注意

awslogs-region 日志选项或检测到的区域控制用于签名的区域。如果您使用 awslogs-endpoint 指定的终端节点使用不同的区域，您可能会遇到签名错误。

awslogs-group

您必须为 日志组 指定awslogs日志驱动程序。您可以通过 awslogs-group 日志选项指定日志组：

$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 --log-opt awslogs-group=myLogGroup ...

awslogs-stream

要配置应使用哪个 日志流 ，您可以指定 awslogs-stream 日志选项。如果未指定，则使用容器 ID 作为日志流。

注意

给定日志组中的日志流应一次仅由一个容器使用。 并发地为多个容器使用相同的日志流可能会导致日志记录性能下降。

awslogs-create-group

默认情况下，如果日志组不存在，日志驱动程序会返回错误。但是，您可以将 awslogs-create-group 设置为 true 以根据需要自动创建日志组。 awslogs-create-group 选项默认为 false。

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-create-group=true \
    ...

注意

您的 AWS IAM 策略必须包含 logs:CreateLogGroup 权限，然后才能尝试使用 awslogs-create-group。

awslogs-create-stream

默认情况下，日志驱动程序会创建用于容器日志持久化的 AWS CloudWatch Logs 流。

将 awslogs-create-stream 设置为 false 以禁用日志流创建。当禁用时，Docker 守护进程假设 日志流已存在。此功能有益的一个用例是当日志流创建由另一个进程处理时，避免重复的 AWS CloudWatch Logs API 调用。

如果将 awslogs-create-stream 设置为 false 且日志流不存在，则在容器运行期间日志持久化到 CloudWatch 会失败，导致守护程序日志中出现 Failed to put log events 条错误消息。

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-stream=myLogStream \
    --log-opt awslogs-create-stream=false \
    ...

awslogs-datetime-format

awslogs-datetime-format 选项定义了一个多行起始模式，位于 Python strftime 格式 中。日志消息由匹配该模式的行以及所有不匹配该模式的后续行组成。因此，匹配的行是日志消息之间的分隔符。

使用此格式的一个用例示例是解析输出，例如堆栈转储，否则可能会记录在多个条目中。正确的模式允许将其捕获在单个条目中。

如果同时配置了 awslogs-datetime-format 和 awslogs-multiline-pattern，则此选项始终优先。

注意

多行日志记录对所有日志消息执行正则表达式解析和匹配，这可能会对日志记录性能产生负面影响。

考虑以下日志流，其中新的日志消息以 时间戳开头：

[May 01, 2017 19:00:01] A message was logged
[May 01, 2017 19:00:04] Another multi-line message was logged
Some random message
with some random words
[May 01, 2017 19:01:32] Another message was logged

格式可以表示为 strftime 表达式， [%b %d, %Y %H:%M:%S] 的 awslogs-datetime-format 值可以设置为 该表达式：

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-datetime-format='\[%b %d, %Y %H:%M:%S\]' \
    ...

这将日志解析为以下 CloudWatch 日志事件：

# First event
[May 01, 2017 19:00:01] A message was logged

# Second event
[May 01, 2017 19:00:04] Another multi-line message was logged
Some random message
with some random words

# Third event
[May 01, 2017 19:01:32] Another message was logged

支持以下 strftime 个代码：

awslogs-multiline-pattern

awslogs-multiline-pattern 选项使用正则表达式定义多行起始模式。日志消息由匹配该模式的行和所有不匹配该模式的后续行组成。因此，匹配的行是日志消息之间的分隔符。

如果同时配置了 awslogs-datetime-format，则此选项将被忽略。

注意

多行日志对所有日志消息执行正则表达式解析和匹配。这可能会对日志性能产生负面影响。

请考虑以下日志流，其中每条日志消息应以模式 INFO 开头：

INFO A message was logged
INFO Another multi-line message was logged
     Some random message
INFO Another message was logged

您可以使用正则表达式 ^INFO：

$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-multiline-pattern='^INFO' \
    ...

这将日志解析为以下 CloudWatch 日志事件：

# First event
INFO A message was logged

# Second event
INFO Another multi-line message was logged
     Some random message

# Third event
INFO Another message was logged

标签

指定 tag 作为 awslogs-stream 选项的替代。 tag 解析 Go 模板标记，例如 {{.ID}}、{{.FullID}} 或 {{.Name}} docker.{{.ID}}。 有关支持的模板 替换的详细信息，请参阅 标记选项文档。

当同时指定了 awslogs-stream 和 tag 时，为 awslogs-stream 提供的值将覆盖使用 tag 指定的模板。

如果未指定，则使用容器ID作为日志流。

注意

CloudWatch 日志 API 不支持在日志名称中使用 :。这可能会导致在使用 {{ .ImageName }} 作为标签时出现一些问题，因为 Docker 镜像的格式为 IMAGE:TAG，例如 alpine:latest。可以使用模板标记来获取正确的格式。要获取镜像名称和容器 ID 的前 12 个字符，可以使用：

--log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}'

输出结果类似于：alpine_latest-bf0072049c76

awslogs-force-flush-interval-seconds

awslogs 驱动定期将日志刷新到 CloudWatch。

awslogs-force-flush-interval-seconds 选项更改日志刷新间隔秒数。

默认为5秒。

awslogs-max-buffered-events

awslogs 驱动程序会缓冲日志。

awslogs-max-buffered-events 选项更改日志缓冲区大小。

默认为 4K。

凭据

要使用 awslogs 日志驱动程序，必须向 Docker 守护进程提供 AWS 凭证。您可以通过 AWS_ACCESS_KEY_ID、 AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 环境变量、 默认 AWS 共享凭证文件（根用户的 ~/.aws/credentials），或者 如果您在 Amazon EC2 实例上运行 Docker 守护进程，则可以使用 Amazon EC2 实例配置文件来提供这些凭证。

凭据必须应用一个允许 logs:CreateLogStream 和 logs:PutLogEvents 操作的策略，如以下示例所示。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}