Amazon CloudWatch Logs 로깅 드라이버

Amazon CloudWatch Logs 로깅 드라이버 (Amazon CloudWatch Logs logging driver)

awslogs 로깅 드라이버는 컨테이너 로그를 Amazon CloudWatch Logs로 보내요. 로그 항목은 AWS Management Console 또는 AWS SDKs and Command Line Tools로 검색할 수 있어요.

출처: 문서

본문

사용법 (Usage)

awslogs 드라이버를 기본 로깅 드라이버로 사용하려면 daemon.json 파일에서 log-driver와 log-opt 키를 적절한 값으로 설정해요. daemon.json으로 Docker를 구성하는 것에 대한 자세한 내용은 daemon.json을 참고하세요.

Note Docker Desktop을 사용한다면 Docker Desktop Dashboard를 통해 데몬 구성을 편집해요. Settings를 열고 Docker Engine을 선택해요. 자세한 내용은 Docker Engine 설정을 참고하세요.

다음 예시는 로그 드라이버를 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 옵션 (Amazon CloudWatch Logs options)

Docker 전역 기본값을 설정하려면 daemon.json에 로깅 옵션을 추가하거나, 컨테이너를 시작할 때 --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 로그 옵션을 사용해 기본 엔드포인트를 제공된 엔드포인트로 재정의해요.

Note 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가 로그 스트림으로 사용돼요.

Note 주어진 로그 그룹 내의 로그 스트림은 한 번에 하나의 컨테이너만 사용해야 해요. 여러 컨테이너가 동시에 같은 로그 스트림을 사용하면 로깅 성능이 저하될 수 있어요.

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

Note AWS IAM 정책에 awslogs-create-group을 사용하기 전에 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이 모두 구성되면 이 옵션이 항상 우선해요.

Note 멀티라인 로깅은 모든 로그 메시지의 정규식 파싱과 매칭을 수행하며, 이는 로깅 성능에 부정적 영향을 줄 수 있어요.

새 로그 메시지가 타임스탬프로 시작하는 다음 로그 스트림을 고려해요:

[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

형식은 [%b %d, %Y %H:%M:%S]의 strftime 표현식으로 나타낼 수 있고, 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 코드가 지원돼요:

Code	Meaning	Example
%a	요일 축약 이름.	Mon
%A	요일 전체 이름.	Monday
%w	0이 일요일, 6이 토요일인 십진수 요일.	0
%d	월 중 일을 0으로 채운 십진수.	08
%b	월 축약 이름.	Feb
%B	월 전체 이름.	February
%m	월을 0으로 채운 십진수.	02
%Y	세기를 포함한 연도를 십진수.	2008
%y	세기 없는 연도를 0으로 채운 십진수.	08
%H	시(24시간)를 0으로 채운 십진수.	19
%I	시(12시간)를 0으로 채운 십진수.	07
%p	AM 또는 PM.	AM
%M	분을 0으로 채운 십진수.	57
%S	초를 0으로 채운 십진수.	04
%f	마이크로초를 0으로 채운 십진수.	000345
%z	+HHMM 또는 -HHMM 형태의 UTC 오프셋.	+1300
%Z	시간대 이름.	PST
%j	연 중 일을 0으로 채운 십진수.	363

또한 다음 비-strftime 코드도 지원돼요:

Code	Meaning	Example
%L	마침표 앞의 0으로 채운 십진수 밀리초.	.123

awslogs-multiline-pattern

awslogs-multiline-pattern 옵션은 정규식을 사용해 멀티라인 시작 패턴을 정의해요. 로그 메시지는 패턴과 일치하는 줄과 그 뒤의 패턴과 일치하지 않는 줄들로 구성돼요. 따라서 일치하는 줄이 로그 메시지 간의 구분 기호예요.

awslogs-datetime-format도 구성되면 이 옵션은 무시돼요.

Note 멀티라인 로깅은 모든 로그 메시지의 정규식 파싱과 매칭을 수행해요. 이는 로깅 성능에 부정적 영향을 줄 수 있어요.

각 로그 메시지가 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를 지정해요. tag는 {{.ID}}, {{.FullID}}, {{.Name}} docker.{{.ID}} 같은 Go 템플릿 마크업을 해석해요. 지원되는 템플릿 대체에 대한 자세한 내용은 tag 옵션 문서를 참고하세요.

awslogs-stream과 tag가 모두 지정되면 awslogs-stream에 제공된 값이 tag로 지정된 템플릿을 재정의해요.

지정하지 않으면 컨테이너 ID가 로그 스트림으로 사용돼요.

Note CloudWatch 로그 API는 로그 이름에서 :를 지원하지 않아요. Docker 이미지가 alpine:latest 같은 IMAGE:TAG 형식이므로 {{ .ImageName }}을 태그로 사용할 때 문제가 발생할 수 있어요. 적절한 형식을 얻기 위해 템플릿 마크업을 사용할 수 있어요. 이미지 이름과 컨테이너 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예요.

자격 증명 (Credentials)

awslogs 로깅 드라이버를 사용하려면 AWS 자격 증명을 Docker 데몬에 제공해야 해요. 자격 증명은 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN 환경 변수, 기본 AWS 공유 자격 증명 파일(루트 사용자의 ~/.aws/credentials), 또는 Amazon EC2 인스턴스에서 Docker 데몬을 실행 중이라면 Amazon EC2 인스턴스 프로필로 제공할 수 있어요.

Note Docker는 컨테이너가 시작될 때 AWS 자격 증명을 읽어요. 임시 자격 증명이 있는 공유 AWS 자격 증명 파일을 사용한다면, 나중에 파일을 업데이트해도 실행 중인 컨테이너가 사용하는 자격 증명이 자동으로 업데이트되지 않아요. 임시 자격 증명이 만료되면 Amazon CloudWatch Logs로의 로그 전달이 실패할 수 있어요. Docker가 업데이트된 값을 로드할 수 있도록 자격 증명을 새로고친 후 컨테이너를 재시작해요.

자격 증명에는 다음 예시와 같이 logs:CreateLogStream과 logs:PutLogEvents 액션을 허용하는 정책이 적용되어야 해요.

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

더 알아보기 (Learn more)

• 로깅 개요
• 로깅 드라이버 구성