Fluentd Docker 사용하기
Docker를 이용한 Fluentd 로그 전송¶
Fluentd를 설치하지 않아도 Docker를 사용해 애널리틱스 서버로 로그를 전송할 수 있습니다. hive_fluentd.sh를 실행하면 Docker 이미지 생성, 실행까지 한 번에 수행합니다.
사전 준비¶
Docker를 쓸 수 있는 환경을 마련하고, 자동화 스크립트를 다운로드합니다.
Docker 환경 설정¶
Docker 사용을 위해서는 docker engine, docker-compose를 설치해야 합니다. 자세한 내용은 다음을 확인하세요.
자동화 스크립트 다운로드¶
파일을 다운받고 압축을 풉니다.
wget https://developers.withhive.com/wp-content/uploads/2024/08/hive_fluentd_docker.tar # 파일 다운로드
tar -xvf hive_fluentd_docker.tar # 압축해제
파일 압축을 풀면 hive_fluentd_docker 폴더 내에서 환경 설정 파일인 hive.conf와 스크립트 파일인 hive_fluentd.sh를 확인 가능합니다.
hive.conf 설정¶
개발 언어별(Java, Python 등) 라이브러리를 사용할 때 설정과 특정 로그 파일을 전송할 때 설정이 있습니다.
개발 언어별 라이브러리 사용 시 Config¶
빌드 환경(sandbox 또는 live) 설정만 작성합니다. 아래 예시를 참고하세요.
### hive.conf ###
# 빌드 환경 sandbox 또는 live 만 사용 가능합니다. 환경에 맞는 hive 서버로 로그가 전송 됩니다.
# 그 외 텍스트는 수정하지 말아주세요
build:sandbox
### don't delete this line ####
라이브러리로 전송 시 Docker는 24224 포트를 통해 로그 서버로 로그를 전송합니다.
특정 로그 파일을 전송 시 Config¶
파일이 위치한 경로(절대 경로)와 tag를 작성합니다. 로그 폴더가 여러 개이면 path와 tag를 함께 추가해야 합니다.
다음은 로그 폴더가 하나인 경우 예시입니다.
### hive.conf ###
build:sandbox # 빌드 환경 sandbox, live만 사용 가능하며 각 환경에 맞는 hive 서버로 로그가 전송 됩니다
# path : 전송할 파일이 위치한 폴더 경로 (절대 경로)
# fluentd가 실행된 이후 해당 경로에 있는 모든 파일에 추가되는 텍스트 라인부터 전송 됩니다.
path:/home/user1/docker/shell_test/game
# tag : 해당 파일에 적용할 tag명 , ha2union.game.로그카테고리명
tag:ha2union.game.log.test
### don't delete this line ####
다음은 로그 폴더가 여럿인 경우 예시입니다.
### hive.conf ###
build:sandbox # 빌드 환경 sandbox, live만 사용 가능하며 각 환경에 맞는 hive 서버로 로그가 전송 됩니다
# path : 전송할 파일이 위치한 폴더 경로 (절대 경로)
# fluentd가 실행된 이후 해당 경로에 있는 모든 파일에 추가되는 텍스트 라인부터 전송 됩니다.
path:/home/user1/docker/shell_test/game
# tag : 해당 파일에 적용할 tag명 , ha2union.game.로그카테고리명
# tag에 대한 자세한 내용은 https://developers.withhive.com/ko/dev4/analytics/hive-send-log/fluentd/ 참고
tag:ha2union.game.log.test
# 파일 경로가 다수인 경우 아래와 같은 방식으로 추가 하면 됩니다.
# 꼭 path와 tag는 함께 추가 되어야 하며 비어있는 경우 오류가 발생합니다.
path:/home/user1/docker/shell_test/game2
tag:ha2union.game.log.test2
path:/home/user1/docker/shell_test/game3
tag:ha2union.game.log.test3
### don't delete this line ####
Config 파일 최상단과 최하단 텍스트는 수정하시면 안 됩니다.
build¶
로그를 전송할 애널리틱스 서버 종류입니다. sandbox 또는 live입니다. 애널리틱스 샌드박스 서버 또는 애널리틱스 라이브 서버를 의미합니다.
path¶
전송할 로그 파일이 있는 폴더 경로(절대 경로)입니다. 로그 파일은 JSON 파일이어야 합니다. hive_fluentd.sh 스크립트 실행으로 Docker가 정상 실행된 후, 이 경로에 있는 모든 파일에 추가되는 라인부터 서버로 전송합니다. 즉, 폴더에 기존 로그 파일이 있더라도 Docker가 동작을 시작한 후에 파일에 새로 추가되는 라인부터 로그를 읽어 전송합니다. 이후에는 로그를 읽어온 위치를 기억하므로 Docker를 재시작해도 기존 전송을 완료한 다음 라인을 전송합니다.
tag¶
path에 있는 로그들에 적용할 tag를 기재합니다. tag는 반드시 ha2union.game.작성할\_명칭 형식으로 작성합니다.
자동화 스크립트 실행과 확인¶
Config 설정을 완료했다면 이제 hive_fluentd.sh를 실행합니다.
스크립트를 실행하면 Docker 이미지 생성부터 Docker 실행 후 로그 전송까지 자동으로 수행합니다. 실행 오류가 발생한다면 Config를 올바르게 설정했는지 다시 확인합니다. 아래와 같은 메세지가 나오면 성공입니다. pull access denied 관련 메세지는 무시합니다.
[+] Running 1/1
! fluentd Warning pull access denied for com2usplatform/hive_analytics_fluentd_docker, repository does not exist or may require 'docker login': deni... 2.8s
[+] Building 2.1s (8/8) FINISHED docker:default
=> [fluentd internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 145B 0.0s
=> [fluentd internal] load metadata for docker.io/fluent/fluentd:v1.11.4-debian-1.0 1.9s
=> [fluentd auth] fluent/fluentd:pull token for registry-1.docker.io 0.0s
=> [fluentd internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [fluentd 1/2] FROM docker.io/fluent/fluentd:v1.11.4-debian-1.0@sha256:b70acf966c6117751411bb638bdaa5365cb756ad13888cc2ccc0ba479f13aee7 0.0s
=> CACHED [fluentd 2/2] RUN ["gem", "install", "fluent-plugin-forest"] 0.0s
=> [fluentd] exporting to image 0.0s
=> => exporting layers 0.0s
=> => writing image sha256:857dc72492380aeb31bbee36b701f13ae5ae1a933b46945662657246b28964a5 0.0s
=> => naming to docker.io/com2usplatform/hive_analytics_fluentd_docker:sandbox 0.0s
=> [fluentd] resolving provenance for metadata file 0.0s
[+] Running 2/2
✔ Network shell_test_default Created 0.1s
✔ Container hive_analytics_fluentd_docker_sandbox Started 0.5s
정상적으로 실행이 완료되면 로그를 전송하기 시작합니다.
참고¶
명령어, 로그 확인 방법, 파일 구조, forest 로그 확인 등을 안내합니다.
명령어¶
다음은 명령어 모음입니다.
재시작¶
hive.conf 파일을 기준으로 fluentd.conf, docker-compose 파일을 재생성하여 Container를 다시 올립니다. 재시작했더라도 기존에 생성한 폴더와 pos 파일이 있다면, 기존에 로그를 전송했던 부분 이후부터 이어서 전송을 시작합니다.
일시 정지¶
Docker 이미지를 일시 정지합니다.
정지된 이미지 다시 실행¶
정지한 Docker 이미지를 다시 실행합니다.
Docker Container 삭제¶
Container를 삭제합니다.
로그 확인 방법¶
아래 명령어로 로그를 확인 합니다.
명령어 정상 실행 시 로그 예시는 아래와 같습니다.
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: parsing config file is succeeded path="/fluentd/etc/fluent.conf"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: gem 'fluent-plugin-forest' version '0.3.3'
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: gem 'fluentd' version '1.11.4'
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: adding forwarding server 'sandbox-analytics-hivelog' host="sandbox-analytics-hivelog.withhive.com" port=24224 weight=60 plugin_id="object:3fcfa2188060"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: using configuration file:
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | log\_level info
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | @type forward
hive\_analytics\_fluentd\_docker\_sandbox | skip\_invalid\_event true
hive\_analytics\_fluentd\_docker\_sandbox | chunk\_size\_limit 10m
hive\_analytics\_fluentd\_docker\_sandbox | chunk\_size\_warn\_limit 9m
hive\_analytics\_fluentd\_docker\_sandbox | port 24224
hive\_analytics\_fluentd\_docker\_sandbox | bind "0.0.0.0"
hive\_analytics\_fluentd\_docker\_sandbox | source\_address\_key "fluentd\_sender\_ip"
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | @type copy
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | @type "forest"
hive\_analytics\_fluentd\_docker\_sandbox | subtype "file"
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | time\_slice\_format %Y%m%d%H
hive\_analytics\_fluentd\_docker\_sandbox | time\_slice\_wait 10s
hive\_analytics\_fluentd\_docker\_sandbox | path /fluentd/forest/${tag}/${tag}
hive\_analytics\_fluentd\_docker\_sandbox | compress gz
hive\_analytics\_fluentd\_docker\_sandbox | format json
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | @type "forward"
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | @type "file"
hive\_analytics\_fluentd\_docker\_sandbox | path "/fluentd/buffer/foward\_buffer/"
hive\_analytics\_fluentd\_docker\_sandbox | chunk\_limit\_size 10m
hive\_analytics\_fluentd\_docker\_sandbox | flush\_interval 3s
hive\_analytics\_fluentd\_docker\_sandbox | total\_limit\_size 16m
hive\_analytics\_fluentd\_docker\_sandbox | flush\_thread\_count 16
hive\_analytics\_fluentd\_docker\_sandbox | queued\_chunks\_limit\_size 16
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | name "sandbox-analytics-hivelog"
hive\_analytics\_fluentd\_docker\_sandbox | host "sandbox-analytics-hivelog.withhive.com"
hive\_analytics\_fluentd\_docker\_sandbox | port 24224
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox | @type "secondary\_file"
hive\_analytics\_fluentd\_docker\_sandbox | directory "/fluentd/failed/log/forward-failed/send-failed-file"
hive\_analytics\_fluentd\_docker\_sandbox | basename "dump.${tag}.${chunk\_id}"
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive\_analytics\_fluentd\_docker\_sandbox |
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: starting fluentd-1.11.4 pid=7 ruby="2.6.6"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: spawn command to main: cmdline=["/usr/local/bin/ruby", "-Eascii-8bit:ascii-8bit", "/usr/local/bundle/bin/fluentd", "-c", "/fluentd/etc/fluent.conf", "-p", "/fluentd/plugins", "--under-supervisor"]
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: adding match pattern="ha2union.**" type="copy"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: #0 adding forwarding server 'sandbox-analytics-hivelog' host="sandbox-analytics-hivelog.withhive.com" port=24224 weight=60 plugin_id="object:3f8185f73f64"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: adding source type="forward"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: #0 starting fluentd worker pid=17 ppid=7 worker=0
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: #0 listening port port=24224 bind="0.0.0.0"
hive_analytics_fluentd_docker_sandbox | 2024-08-19 07:19:31 +0000 [info]: #0 fluentd worker is now running worker=0
파일 구조¶
스크립트 첫 실행 시 아래와 같이 필요한 설정 파일과 폴더들을 자동으로 생성합니다. 설정 파일과 폴더들을 임의로 삭제하지 않는다면, Docker Container를 내리거나 삭제해도 설정 파일과 폴더들은 유지됩니다.
---- hive_fluentd_docker # 다운로드 받은 파일을 압축 해제 시 생성되는 폴더
├-- hive.conf # 환경 설정 파일
├-- hive_fluentd.sh # 자동화 스크립트
├-- docker-compose.yaml # docker 이미지 생성 및 volume mount를 위한 설정 파일
├-- buffer
│ ├-- foward_buffer # buffer 파일이 임시 저장되는 폴더
│ │ ├-- {tag1} # tag명을 기준으로 생성된 폴더에 전송하는 파일을 buffer파일로 임시 보관
│ │ ├-- {tag2}.....
│ ├-- pos # 읽어온 파일의 위치를 기억하는 파일이 저장되는 폴더 (삭제 되거나 변조 등의 문제가 발생 되는 경우 데이터 누락이나 중복 전송이 될 수 있음)
│ │ ├-- {tag1} # tag명을 기준으로 생성된 폴더에 pos 파일 저장
│ │ ├-- {tag2}.....
├-- conf
│ └-- fluentd.conf # fluentd 설정 파일
├-- failed # 전송에 실패한 로그를 파일로 보관
└-- forest # 전송이 완료된 파일을 시간 단위로 모아 압축하여 보관
forest 로그 확인¶
forest 폴더에 로그 파일을 전송했을 때 사용한 tag명으로 폴더를 생성합니다. 임시 파일 상태로 일정 시간 쌓이다가 최종적으로 gzip 파일로 저장합니다. 폴더에 파일이 생성되고 파일 용량 증가를 확인함으로써 로그가 잘 전송되고 있음을 알 수 있습니다.
drwxr-xr-x 2 root root 4096 Aug 23 13:00 ha2union.game.sample.login/
-rw-r--r-- 1 root root 4515 Aug 23 13:00 ha2union.game.sample.login.2024082303_0.log.gz
-rw-r--r-- 1 root root 4515 Aug 23 12:00 ha2union.game.sample.login.2024082302_0.log.gz
압축 파일은 아래와 같은 명령어로 로그를 확인합니다.