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 以使更改生效。

您可以使用 docker run 的 --log-driver 選項為特定容器設定日誌記錄驅動程式。

$ 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 \
    ...

注意

在嘗試使用 awslogs-create-group 之前，您的 AWS IAM 策略必須包含 logs:CreateLogGroup 許可權。

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

將 tag 指定為 awslogs-stream 選項的替代方案。tag 會解釋 Go 模板標記，例如 {{.ID}}、{{.FullID}} 或 {{.Name}} docker.{{.ID}}。有關支援的模板替換的詳細資訊，請參閱 tag 選項文件。

當同時指定 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。

憑據

您必須向 Docker 守護程序提供 AWS 憑據才能使用 awslogs 日誌記錄驅動程式。您可以透過 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 環境變數、預設的 AWS 共享憑據檔案（root 使用者的 ~/.aws/credentials），或者如果您在 Amazon EC2 例項上執行 Docker 守護程序，則透過 Amazon EC2 例項配置檔案來提供這些憑據。

憑據必須應用允許 logs:CreateLogStream 和 logs:PutLogEvents 操作的策略，如以下示例所示。

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