Amazon CloudWatch Logs
사용 설명서

CloudWatch Logs 에이전트 참조

CloudWatch Logs 에이전트는 Amazon EC2 인스턴스에서 CloudWatch Logs로 로그 데이터를 자동 전송할 수 있게 해줍니다. 에이전트는 다음과 같은 구성 요소로 이루어져 있습니다.

  • CloudWatch Logs에 로그 데이터를 푸시하기 위한 AWS CLI 플러그인 기능입니다.

  • CloudWatch Logs로 데이터를 푸시하는 프로세스를 시작하는 스크립트(데몬)입니다.

  • 데몬이 항상 실행되도록 하는 cron 작업입니다.

에이전트 구성 파일

CloudWatch Logs 에이전트 구성 파일은 CloudWatch Logs 에이전트에 필요한 정보를 설명합니다. 에이전트 구성 파일의 [general] 섹션은 모든 로그 스트림에 적용되는 공통 구성을 정의합니다. [logstream] 섹션은 원격 로그 스트림에 로컬 파일을 전송하는 데 필요한 정보를 정의합니다. [logstream] 섹션은 하나 이상 정의가 가능하지만, 각 섹션은 구성 파일 내에 고유한 이름을 가져야 합니다(예: [logstream1], [logstream2] 등). 로그 파일에 있는 데이터의 첫 줄과 함께 [logstream] 값은 로그 파일의 ID를 정의합니다.

[general] state_file = value logging_config_file = value use_gzip_http_content_encoding = [true | false] [logstream1] log_group_name = value log_stream_name = value datetime_format = value time_zone = [LOCAL|UTC] file = value file_fingerprint_lines = integer | integer-integer multi_line_start_pattern = regex | {datetime_format} initial_position = [start_of_file | end_of_file] encoding = [ascii|utf_8|..] buffer_duration = integer batch_count = integer batch_size = integer [logstream2] ...
상태 파일

상태 파일이 저장되는 장소를 지정합니다.

logging_config_file

(선택 사항) 에이전트 로깅 구성 파일의 위치를 지정합니다. 여기에서 에이전트 로깅 구성 파일을 지정하지 않으면 기본 파일인 awslogs.conf가 사용됩니다. 스크립트를 통해 에이전트를 설치한 경우 기본 파일 위치는 /var/awslogs/etc/awslogs.conf이고, rpm을 통해 에이전트를 설치한 경우 /etc/awslogs/awslogs.conf입니다. 이 파일은 Python 구성 파일 형식을 가지고 있습니다(https://docs.python.org/2/library/logging.config.html#logging-config-fileformat). 다음 이름을 가진 로거를 사용자가 지정할 수 있습니다.

cwlogs.push cwlogs.push.reader cwlogs.push.publisher cwlogs.push.event cwlogs.push.batch cwlogs.push.stream cwlogs.push.watcher

아래 샘플은 기본 값이 INFO인 경우 독자와 게시자의 수준을 WARNING으로 수준을 변경합니다.

[loggers] keys=root,cwlogs,reader,publisher [handlers] keys=consoleHandler [formatters] keys=simpleFormatter [logger_root] level=INFO handlers=consoleHandler [logger_cwlogs] level=INFO handlers=consoleHandler qualname=cwlogs.push propagate=0 [logger_reader] level=WARNING handlers=consoleHandler qualname=cwlogs.push.reader propagate=0 [logger_publisher] level=WARNING handlers=consoleHandler qualname=cwlogs.push.publisher propagate=0 [handler_consoleHandler] class=logging.StreamHandler level=INFO formatter=simpleFormatter args=(sys.stderr,) [formatter_simpleFormatter] format=%(asctime)s - %(name)s - %(levelname)s - %(process)d - %(threadName)s - %(message)s
use_gzip_http_content_encoding

true(기본)로 설정되어 있으면 gzip http 콘텐츠 인코딩을 활성화하여 CloudWatch Logs로 압축된 페이로드를 전송합니다. 이렇게 하면 CPU 사용량을 줄이고 NetworkOut을 낮추며 PUT 레코드 지연 시간을 줄일 수 있습니다. 이 기능을 비활성화하려면 CloudWatch Logs 에이전트 구성 파일의 [general] 섹션에 use_gzip_http_content_encoding = false를 추가한 다음, 에이전트를 다시 시작합니다.

참고

이 설정은 awscli-cwlogs 버전 1.3.3 이상에서만 사용할 수 있습니다.

log_group_name

대상 로그 그룹을 지정합니다. 로그 그룹이 없는 경우 이 설정에 따라 로그 그룹이 자동으로 생성됩니다. 로그 그룹 이름에 포함되는 문자 길이는 1~512자입니다. 허용되는 문자: a-z, A-Z, 0-9, '_'(밑줄), '- (하이픈), '/'(슬래시) 및 '.'(마침표)

log_stream_name

대상 로그 스트림을 지정합니다. 리터럴 문자열이나 미리 정의된 변수({instance_id}, {hostname}, {ip_address}) 또는 이 둘의 조합을 사용하여 로그 스트림 이름을 정의할 수 있습니다. 로그 스트림이 없는 경우 이 설정에 따라 로그 스트림이 자동으로 생성됩니다.

datetime_format

타임스탬프가 로그에서 추출되는 방법을 지정합니다. 타임스탬프는 로그 이벤트를 검색하고 지표를 생성하는 데 사용됩니다. datetime_format이 제공되지 않는 경우에는 각 로그 이벤트에서 현재 시간이 사용됩니다. 제공된 datetime_format 값이 해당 로그 메시지에서 유효하지 않으면 타임스탬프가 성공적으로 구문 분석된 마지막 로그 이벤트에서 나온 타임스탬프가 사용됩니다. 이전 로그 이벤트가 존재하지 않는 경우 현재 시간이 사용됩니다.

공통적인 datetime_format 코드가 아래에 나열되어 있습니다. Python, datetime.strptime()에서 지원되는 datetime_format 코드면 무엇이든 사용 가능합니다. 시간대 오프셋(%z)도 지원되기는 하지만, 콜론(:)이 없는 python 3.2, [+-]HHMM이 나올 때까지는 지원되지 않습니다. 자세한 내용은 strftime() 및 strptime() 동작을 참조하십시오.

%y: 제로 패딩된 10진수 형태의 세기를 제외한 연도. 00, 01, ..., 99

%Y: 10진수 형태의 세기를 포함한 연도. 1970, 1988, 2001, 2013

%b: 로캘 약어 형태의 월. Jan, Feb, ..., Dec (en_US);

%B: 로캘 전체 이름 형태의 월. January, February, ..., December (en_US);

%m: 제로 패딩된 10진수 형태의 월. 01, 02, ..., 12

%d: 제로 패딩된 10진수 형태의 월 날짜. 01, 02, ..., 31

%H: 제로 패딩된 10진수 형태의 시간(24시간 방식). 00, 01, ..., 23

%I: 제로 패딩된 10진수 형태의 시간(12시간 방식). 01, 02, ..., 12

%p: AM 또는 PM 중 하나에 상응하는 로캘.

%M: 제로 패딩된 10진수 형태의 분. 00, 01, ..., 59

%S: 제로 패딩된 10진수 형태의 초. 00, 01, ..., 59

%f: 왼쪽이 제로 패딩된 10진수 형태의 마이크로초. 000000, ..., 999999

%z: +HHMM 또는 -HHMM 형태의 UTC 오프셋. +0000, -0400, +1030

형식의 예:

Syslog: '%b %d %H:%M:%S', e.g. Jan 23 20:59:29

Log4j: '%d %b %Y %H:%M:%S', e.g. 24 Jan 2014 05:00:00

ISO8601: '%Y-%m-%dT%H:%M:%S%z', e.g. 2014-02-20T05:20:20+0000

time_zone

로그 이벤트 타임스탬프의 시간대를 지정합니다. UTC 및 LOCAL 등 2개의 값이 지원됩니다. 기본값인 LOCAL은 datetime_format에 따라 시간대를 추정할 수 없을 때 사용됩니다.

file

CloudWatch Logs에 푸시하고 싶은 로그 파일을 지정합니다. 파일은 특정 파일을 가리키거나 여러 개의 파일을 가리킬 수 있습니다(/var/log/system.log* 같은 와일드카드를 사용). 파일 수정 시간에 따라 최신 파일만 CloudWatch Logs로 푸시됩니다. 와일드카드는 여러 종류의 파일(예: access_log_80 및 access_log_443)이 아니라 종류가 같은 일련의 파일(예: access_log.2014-06-01-01, access_log.2014-06-01-02 등)을 지정할 때 사용하는 것이 좋습니다. 여러 종류의 파일을 지정하려면 로그 파일의 종류에 따라 다른 로그 스트림에 들어가도록 구성 파일에 또 다른 로그 스트림 항목을 추가합니다. 압축 파일은 지원되지 않습니다.

file_fingerprint_lines

파일을 식별하기 위한 줄의 범위를 지정합니다. 유효한 값은 하나의 숫자(예: '1')나 대시로 구분된 두 개의 숫자(예: '2-5')입니다. 기본값은 '1'이기 때문에 지문 산출을 위해 첫 번째 줄이 사용됩니다. 지정된 모든 줄이 사용 가능한 상태가 되지 않는 한, 지문 줄은 CloudWatch Logs로 전송되지 않습니다.

multi_line_start_pattern

로그 메시지의 시작을 식별하기 위해 패턴을 지정합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 유효한 값은 정규식 또는 {datetime_format}입니다. {datetime_format}을 사용할 때는 반드시 datetime_format 옵션이 지정되어 있어야 합니다. 기본값은 ‘^[^\s]'이기 때문에 공백이 아닌 문자로 시작되는 줄이 있으면 이전의 로그 메시지가 종료되고 새로운 로그 메시지가 시작됩니다.

initial_position

데이터 읽기를 시작할 지점(start_of_file 또는 end_of_file)을 지정합니다. 기본값은 파일의 시작 지점입니다. 해당 로그 스트림에서 지속되는 상태가 없을 때만 사용됩니다.

encoding

파일을 정확하게 읽을 수 있도록 로그 파일의 인코딩을 설정합니다. 기본값은 utf_8입니다. Python codecs.decode()에서 지원되는 인코딩을 여기에서 사용할 수 있습니다.

주의

인코딩을 잘못 지정하면 디코딩이 불가능한 문자를 다른 문자들이 대체하면서 데이터 손실이 야기될 수 있습니다.

다음은 몇 가지 일반적인 인코딩입니다.

ascii, big5, big5hkscs, cp037, cp424, cp437, cp500, cp720, cp737, cp775, cp850, cp852, cp855, cp856, cp857, cp858, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, cp874, cp875, cp932, cp949, cp950, cp1006, cp1026, cp1140, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, cp1257, cp1258, euc_jp, euc_jis_2004, euc_jisx0213, euc_kr, gb2312, gbk, gb18030, hz, iso2022_jp, iso2022_jp_1, iso2022_jp_2, iso2022_jp_2004, iso2022_jp_3, iso2022_jp_ext, iso2022_kr, latin_1, iso8859_2, iso8859_3, iso8859_4, iso8859_5, iso8859_6, iso8859_7, iso8859_8, iso8859_9, iso8859_10, iso8859_13, iso8859_14, iso8859_15, iso8859_16, johab, koi8_r, koi8_u, mac_cyrillic, mac_greek, mac_iceland, mac_latin2, mac_roman, mac_turkish, ptcp154, shift_jis, shift_jis_2004, shift_jisx0213, utf_32, utf_32_be, utf_32_le, utf_16, utf_16_be, utf_16_le, utf_7, utf_8, utf_8_sig

buffer_duration

로그 이벤트를 일괄 처리하는 기간을 지정합니다. 최소값은 5000ms이고, 기본값은 5000ms입니다.

batch_count

일괄 처리할 로그 이벤트의 최대 수를 지정합니다(10000까지 가능). 기본값은 10000입니다.

batch_size

일괄 처리할 로그 이벤트의 최대 크기를 바이트로 지정합니다(1048576바이트까지 가능). 기본값은 1048576바이트입니다. 이 크기는 UTF-8에서 모든 이벤트 메시지를 합한 값에 각 로그 이벤트마다 26바이트를 추가하여 계산한 값입니다.

HTTP 프록시와 함께 CloudWatch Logs 에이전트 사용

CloudWatch Logs 에이전트를 HTTP 프록시와 함께 사용할 수 있습니다.

참고

HTTP 프록시는 awslogs-agent-setup.py 버전 1.3.8 이상에서 지원됩니다.

HTTP 프록시와 함께 CloudWatch Logs 에이전트를 사용하려면

  1. 다음 중 하나를 수행하십시오.

    1. CloudWatch Logs 에이전트를 새로 설치하려면 아래 명령을 실행합니다.

      curl https://s3.amazonaws.com/aws-cloudwatch/downloads/latest/awslogs-agent-setup.py -O
      sudo python awslogs-agent-setup.py --region us-east-1 --http-proxy http://your/proxy --https-proxy http://your/proxy --no-proxy 169.254.169.254

      EC2 인스턴스에서 Amazon EC2 메타데이터 서비스에 대한 액세스를 유지하려면 --no-proxy 169.254.169.254를 사용하십시오(권장 사항). 자세한 내용은 Linux 인스턴스용 Amazon EC2 사용 설명서.에서 인스턴스 메타데이터 및 사용자 데이터 단원을 참조하십시오.

      http-proxyhttps-proxy 값에서 전체 URL을 지정합니다.

    2. 기존에 CloudWatch Logs 에이전트가 설치되어 있는 경우에는 /var/awslogs/etc/proxy.conf를 편집해서 프록시를 추가하십시오.

      HTTP_PROXY= HTTPS_PROXY= NO_PROXY=
  2. 에이전트를 다시 시작하면 변경 사항이 적용됩니다.

    sudo service awslogs restart

    Amazon Linux 2를 사용 중인 경우 다음 명령과 함께 에이전트를 다시 시작합니다.

    sudo service awslogsd restart

CloudWatch Logs 에이전트 구성 파일 분류

awslogs-agent-setup.py 버전 1.3.8 이상을 awscli-cwlogs 1.3.3 이상과 함께 사용하면 /var/awslogs/etc/config/ 디렉터리에서 추가 구성 파일을 생성하여 다양한 구성 요소들에 대해 서로 다른 스트림 구성을 독립적으로 가져올 수 있습니다. CloudWatch Logs 에이전트가 시작될 때 이러한 추가 구성 파일에 스트림 구성이 포함됩니다. [general] 섹션의 구성 속성들은 반드시 기본 구성 파일(/var/awslogs/etc/awslogs.conf)에 정의되어 있어야 하며, /var/awslogs/etc/config/에 있는 추가 구성 파일에서는 무시가 됩니다.

rpm을 통해 에이전트를 설치하지 않았기 때문에 /var/awslogs/etc/config/ 디렉터리가 없는 경우 /etc/awslogs/config/ 디렉터리를 대신 사용할 수 있습니다.

에이전트를 다시 시작하면 변경 사항이 적용됩니다.

sudo service awslogs restart

Amazon Linux 2를 사용 중인 경우 다음 명령과 함께 에이전트를 다시 시작합니다.

sudo service awslogsd restart

CloudWatch Logs 에이전트 FAQ

어떤 종류의 파일 로테이션이 지원됩니까?

다음과 같은 파일 로테이션 메커니즘이 지원되고 있습니다.

  • 숫자 접미사를 붙여서 기존 로그 파일의 이름을 바꾸고 원래 빈 로그 파일을 다시 생성하는 방법입니다. 예를 들어 /var/log/syslog.log는 /var/log/syslog.log.1로 이름이 바뀝니다. 이전 로테이션에서 /var/log/syslog.log.1이 이미 존재하는 경우에는 /var/log/syslog.log.2로 이름이 바뀝니다.

  • 복사본을 생성한 후에 원래 로그 파일을 잘라냅니다. 예를 들어 /var/log/syslog.log는 /var/log/syslog.log.1에 복사가 된 후 잘립니다. 이 경우 데이터 손실이 발생할 수 있기 때문에 이 파일 로테이션 메커니즘을 사용할 때는 조심해야 합니다.

  • 기존 파일과 같은 공통 패턴을 따르는 파일을 새로 생성하는 방법입니다. 예를 들어 /var/log/syslog.log.2014-01-01이 그대로 남아 있는 상태에서 /var/log/syslog.log.2014-01-02가 생성됩니다.

파일의 지문(소스 ID)은 로그 스트림 키와 파일 콘텐츠의 첫 줄을 해싱하여 산출됩니다. 이 동작을 재정의하기 위해 file_fingerprint_lines 옵션을 사용할 수 있습니다. 파일 로테이션이 일어나면 새 파일은 새 콘텐츠를 가진 것으로 간주되지만, 기존 파일은 콘텐츠가 추가된 것으로 간주되지 않습니다. 따라서 에이전트는 기존 파일에 대한 읽기를 마치고 나면 새 파일을 푸시합니다.

사용 중인 에이전트의 버전을 어떻게 확인할 수 있습니까?

설정 스크립트를 사용해 CloudWatch Logs 에이전트를 설치했다면 /var/awslogs/bin/awslogs-version.sh를 사용해 사용 중인 에이전트의 버전을 확인할 수 있습니다. 에이전트의 버전과 중요한 플러그인들이 출력됩니다. yum을 사용해 CloudWatch Logs 에이전트를 설치했다면 "yum info awslogs""yum info aws-cli-plugin-cloudwatch-logs"를 사용해 CloudWatch Logs 에이전트의 버전과 플러그인을 확인할 수 있습니다.

로그 항목들은 어떻게 로그 이벤트로 변환됩니까?

로그 이벤트에는 이벤트가 발생한 시점에 대한 타임스탬프와 원시 로그 메시지 등 두 개의 속성이 포함되어 있습니다. 기본적으로 공백이 아닌 문자로 시작되는 줄이 있으면 이전의 로그 메시지가 종료되고 새로운 로그 메시지가 시작됩니다. 이 동작을 재정의하기 위해 multi_line_start_pattern을 사용할 수 있으면 패턴과 일치하는 모든 줄에서 새로운 로그 메시지가 시작됩니다. 어떤 regex 또는 {datetime_format}이든 패턴이 될 수 있습니다. 예를 들어 모든 로그 메시지의 첫 줄에 '2014-01-02T13:13:01Z' 같은 타임스탬프가 포함되어 있으면 multi_line_start_pattern을 '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z'로 설정할 수 있습니다. 간편한 구성을 위해 datetime_format option이 지정되어 있는 경우에 '{datetime_format}' 변수를 사용할 수 있습니다. 같은 예에서 datetime_format이 '%Y-%m-%dT%H:%M:%S%z'로 설정되어 있으면 multi_line_start_pattern이 간단히 '{datetime_format}'이 될 수 있습니다.

datetime_format이 제공되지 않는 경우에는 각 로그 이벤트에서 현재 시간이 사용됩니다. 제공된 datetime_format 값이 해당 로그 메시지에서 유효하지 않으면 타임스탬프가 성공적으로 구문 분석된 마지막 로그 이벤트에서 나온 타임스탬프가 사용됩니다. 이전 로그 이벤트가 존재하지 않는 경우 현재 시간이 사용됩니다. 로그 이벤트가 현재 시간이나 이전 로그 이벤트 시간으로 돌아가면 경고 메시지가 기록됩니다.

타임스탬프는 로그 이벤트를 검색하고 지표를 생성하는 데 사용되기 때문에 형식을 잘못 지정하면 로그 이벤트 검색이 불가능해지고 잘못된 지표가 생성될 수 있습니다.

로그 이벤트는 어떻게 일괄 처리됩니까?

아래 조건 중 어떤 것이든 충족이 되면 배치(batch)가 가득 차면서 게시가 됩니다.

  1. 첫 번째 로그 이벤트가 추가되었기 때문에 buffer_duration 시간이 경과되었습니다.

  2. batch_size 보다 작은 로그 이벤트들이 누적되었지만 새로운 로그 이벤트를 추가하면 batch_size를 초과하게 됩니다.

  3. 로그 이벤트의 수가 batch_count에 도달했습니다.

  4. 배치에서 나온 로그 이벤트들이 24시간 이상 지속되지 않지만, 새 로그 이벤트를 추가하면 24시간이라는 제약 조건을 넘어서게 됩니다.

로그 항목, 로그 이벤트 또는 배치는 어떤 이유로 건너 뛰기가 되거나 잘라집니까?

PutLogEvents 작업의 제약 조건을 따르다보면 다음과 같은 문제들로 인해 로그 이벤트나 배치를 건너 뛰는 상황이 발생할 수 있습니다.

참고

데이터를 건너뛰면 CloudWatch Logs 에이전트가 로그에 경고를 기록합니다.

  1. 로그 이벤트의 크기가 256KB를 초과하면 로그 이벤트가 완전히 건너 뛰기 됩니다.

  2. 로그 이벤트의 타임스탬프가 미래에 2시간 이상이면 해당 로그 이벤트가 건너 뛰기 됩니다.

  3. 로그 이벤트의 타임스탬프가 과거에 14일 이상이었으면 해당 로그 이벤트가 건너 뛰기 됩니다.

  4. 로그 그룹의 보존 기간을 지난 로그 이벤트가 있으면 전체 배치가 건너 뛰기 됩니다.

  5. 단일 PutLogEvents 요청에서 로그 이벤트에 대한 배치가 24시간 이상 지속된 경우에는 PutLogEvents 작업이 실패합니다.

에이전트 중지로 인해 데이터 손실/중복이 발생하고 있습니까?

상태 파일이 사용 가능하고 마지막 실행 이후로 파일 로테이션이 발생하지 않은 한 그렇지 않습니다. CloudWatch Logs 에이전트는 중지된 지점부터 시작해서 로그 데이터를 계속해서 푸시할 수 있습니다.

같은 호스트나 다른 호스트에서 나온 서로 다른 로그 파일이 동일한 로그 스트림으로 가리키도록 할 수 있습니까?

단일 로그 스트림으로 데이터를 전송하기 위해 여러 개의 로그 소스를 구성하는 것이 불가능합니다.

에이전트가 어떤 API를 호출합니까? (또는 IAM 정책에 어떤 작업을 추가해야 합니까?)

CloudWatch Logs 에이전트는 CreateLogGroup, CreateLogStream, DescribeLogStreamsPutLogEvents 작업을 요청합니다. 최신 에이전트를 사용하고 있는 경우에는 DescribeLogStreams가 필요하지 않습니다. IAM 정책 샘플은 아래를 참조하십시오.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams" ], "Resource": [ "arn:aws:logs:*:*:*" ] } ] }
CloudWatch Logs 에이전트에서 로그 그룹이나 로그 스트림이 자동 생성되도록 하고 싶지 않습니다. 어떻게 하면 에이전트가 로그 그룹 또는 로그 스트림을 다시 생성하지 않게 할 수 있습니까?

IAM 정책에서 DescribeLogStreams, PutLogEvents 작업만 수행하도록 에이전트 작업을 제한할 수 있습니다.

에이전트에서 CreateLogGroupCreateLogStream 권한을 취소하기 전에 에이전트에서 사용할 로그 그룹과 로그 스트림을 모두 생성해야 합니다. 로그 에이전트는 CreateLogGroupCreateLogStream 권한이 모두 없는 한 사용자가 생성한 로그 그룹에 로그 스트림을 생성할 수 없습니다.

문제 해결 시 어떤 로그를 살펴봐야 합니까?

에이전트 설치 로그는 /var/log/awslogs-agent-setup.log에, 에이전트 로그는 /var/log/awslogs.log에 있습니다.