Fluentd 로깅 드라이버

Fluentd 로깅 드라이버 (Fluentd logging driver)

fluentd 로깅 드라이버는 컨테이너 로그를 구조화된 로그 데이터로 Fluentd 수집기로 보내요. 그런 다음 사용자는 Fluentd의 다양한 출력 플러그인 중 무엇이든 사용해 이 로그를 다양한 대상에 쓸 수 있어요.

로그 메시지 자체 외에도 fluentd 로그 드라이버는 구조화된 로그 메시지에 다음 메타데이터를 보내요:

Field	Description
`container_id`	전체 64자 컨테이너 ID.
`container_name`	시작된 시점의 컨테이너 이름. `docker rename`으로 컨테이너 이름을 바꾸면 새 이름이 journal 항목에 반영되지 않아요.
`source`	`stdout` 또는 `stderr`
`log`	컨테이너 로그

출처: 문서

본문

사용법 (Usage)

필요한 만큼 --log-opt를 지정해 일부 옵션이 지원돼요:

fluentd-address: Fluentd 데몬에 연결할 소켓 주소 지정, 예: fluentdhost:24224 또는 unix:///path/to/fluentd.sock.
tag: Fluentd 메시지의 태그 지정. 일부 Go 템플릿 마크업 지원, 예: {{.ID}}, {{.FullID}}, {{.Name}} docker.{{.ID}}.

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

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

다음 예시는 로그 드라이버를 fluentd로 설정하고 fluentd-address 옵션을 설정해요.

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

변경 사항을 적용하려면 Docker를 재시작해요.

Note daemon.json 구성 파일의 log-opts 구성 옵션은 문자열로 제공해야 해요. 따라서 부울 및 숫자 값(예: fluentd-async 또는 fluentd-max-retries 값)은 따옴표(")로 감싸야 해요.

특정 컨테이너의 로깅 드라이버를 설정하려면 docker run에 --log-driver 옵션을 전달해요:

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

이 로깅 드라이버를 사용하기 전에 Fluentd 데몬을 시작해요. 로깅 드라이버는 기본적으로 localhost:24224를 통해 이 데몬에 연결해요. fluentd-address 옵션을 사용해 다른 주소에 연결해요.

$ docker run --log-driver=fluentd --log-opt fluentd-address=fluentdhost:24224

컨테이너가 Fluentd 데몬에 연결할 수 없으면 fluentd-async 옵션을 사용하지 않는 한 컨테이너는 즉시 중지돼요.

옵션 (Options)

--log-opt NAME=VALUE 플래그를 사용해 추가 Fluentd 로깅 드라이버 옵션을 지정할 수 있어요.

fluentd-address

기본적으로 로깅 드라이버는 localhost:24224에 연결해요. 다른 주소에 연결하려면 fluentd-address 옵션을 제공해요. tcp(기본값)와 unix 소켓이 지원돼요.

$ docker run --log-driver=fluentd --log-opt fluentd-address=fluentdhost:24224
$ docker run --log-driver=fluentd --log-opt fluentd-address=tcp://fluentdhost:24224
$ docker run --log-driver=fluentd --log-opt fluentd-address=unix:///path/to/fluentd.sock

tcp가 기본이므로 위의 두 개는 같은 주소를 지정해요.

tag

기본적으로 Docker는 컨테이너 ID의 처음 12자를 사용해 로그 메시지에 태그를 붙여요. 로그 태그 형식 사용자 지정에 대해서는 log tag 옵션 문서를 참고하세요.

labels, labels-regex, env, env-regex

labels와 env 옵션은 각각 쉼표 구분 키 목록을 받아요. label과 env 키 사이에 충돌이 있으면 env 값이 우선해요. 두 옵션 모두 로깅 메시지의 추가 속성에 추가 필드를 더해요.

env-regex와 labels-regex 옵션은 각각 env, labels와 유사하고 호환돼요. 그 값은 로깅 관련 환경 변수와 라벨을 일치시키는 정규식이에요. 고급 log tag options에서 사용돼요.

fluentd-async

Docker는 백그라운드에서 Fluentd에 연결해요. 연결이 설정될 때까지 메시지가 버퍼링돼요. 기본값은 false예요.

fluentd-async-reconnect-interval

fluentd-async가 활성화되면 fluentd-async-reconnect-interval 옵션은 fluentd-address와의 연결이 다시 설정되는 간격(밀리초)을 정의해요. 이 옵션은 주소가 하나 이상의 IP 주소로 해석되는 경우(예: Consul 서비스 주소) 유용해요.

fluentd-buffer-limit

메모리에 버퍼링되는 이벤트 수를 설정해요. 레코드는 이 숫자까지 메모리에 저장돼요. 버퍼가 가득 차면 로그를 기록하는 호출이 실패해요. 기본값은 1048576이에요. (https://github.com/fluent/fluent-logger-golang/tree/master#bufferlimit)

fluentd-retry-wait

재시도 사이에 기다리는 시간. 기본값은 1초예요.

fluentd-max-retries

최대 재시도 횟수. 기본값은 4294967295 (2**32 - 1)이에요.

fluentd-sub-second-precision

나노초 해상도로 이벤트 로그를 생성해요. 기본값은 false예요.

fluentd-write-timeout

fluentd 데몬에 대한 쓰기 호출의 타임아웃을 설정해요. 기본적으로 쓰기는 타임아웃이 없고 무기한 블로킹돼요.

Docker로 Fluentd 데몬 관리 (Fluentd daemon management with Docker)

Fluentd 자체에 대해서는 프로젝트 웹페이지와 그 문서를 참고하세요.

이 로깅 드라이버를 사용하려면 호스트에서 fluentd 데몬을 시작해요. the Fluentd docker image를 사용할 것을 권장해요. 이 이미지는 각 호스트의 여러 컨테이너 로그를 집계한 다음, 나중에 로그를 다른 Fluentd 노드로 전송해 집계 저장소를 만들고 싶을 때 특히 유용해요.

테스트 컨테이너 로거 (Test container loggers)

입력 로그를 덤프하는 구성 파일(test.conf)을 작성해요:

<source>
  @type forward
</source>

<match *>
  @type stdout
</match>

이 구성 파일로 Fluentd 컨테이너를 시작해요:

$ docker run -it -p 24224:24224 -v /path/to/conf/test.conf:/fluentd/etc/test.conf -e FLUENTD_CONF=test.conf fluent/fluentd:latest

fluentd 로깅 드라이버로 하나 이상의 컨테이너를 시작해요:

$ docker run --log-driver=fluentd your/application

Fluentd 로깅 드라이버