런타임 로깅

Akan은 structured runtime output을 위해 Logger를 사용하고, AkanApp은 gateway와 child process 로그를 파일로 저장합니다. 터미널 로그는 개발 중 보기 좋게 유지하고, 파일 로그는 사후 확인을 위해 더 자세한 기록을 남깁니다.

Logger API

new Logger(name)

서비스, 어댑터, 스크립트, 런타임 코드에서 이름이 있는 logger를 사용합니다.

터미널 레벨

AKAN_PUBLIC_LOG_LEVEL

stdout과 stderr에 출력할 로그 범위를 제어합니다.

파일 레벨

AKAN_LOG_FILE_LEVEL

Logger 출력 중 파일에 저장할 범위를 제어합니다. 기본값은 trace입니다.

Logger 사용법

컴포넌트나 서비스 이름으로 Logger를 만들고, 의도에 맞는 level로 로그를 남깁니다. 하나의 logger가 여러 작업을 처리한다면 context를 함께 넣습니다.

Service logging

상세 진단에는 trace/debug를, 일반 라이프사이클 이벤트에는 info/log를, 복구 가능한 문제에는 warn을, 작업 실패나 확인이 필요한 상황에는 error를 사용합니다.

로그 레벨

터미널 출력과 파일 출력은 의도적으로 분리되어 있습니다. 운영 서버는 터미널을 info 또는 warn으로 유지하면서도 파일에는 trace 수준의 Logger 기록을 남길 수 있습니다.

.env

터미널

AKAN_PUBLIC_LOG_LEVEL로 제어합니다. 낮은 우선순위 메시지는 stdout/stderr에 출력하지 않습니다.

파일

AKAN_LOG_FILE_LEVEL로 제어합니다. 기본값은 trace라서 터미널이 조용해도 structured Logger 메시지를 보존합니다.

파일 로그와 로테이션

AkanApp이 시작되면 기본적으로 앱 runtime 디렉터리 아래에 파일 로그를 저장합니다. gateway 로그와 child process 로그는 분리되고, 각 process key는 로컬 날짜와 파일 크기 기준으로 독립적으로 회전합니다.

Default log files

Rotation configuration

파일명 형식은 appName-environment-operationMode-YYYY-MM-DD-processKey-sequence.log입니다. 날짜가 바뀌면 해당 날짜의 sequence는 0001부터 다시 시작합니다. 앱이 재시작되면 기존 파일을 덮어쓰지 않고 다음 sequence부터 이어 씁니다.

로그 조회

앱이 트래픽을 받지 못한다면 gateway 로그부터 확인하고, 이후 요청이나 백그라운드 작업을 처리한 child 로그를 확인합니다. child 파일에는 stdout과 stderr prefix가 포함됩니다.

Local lookup

Server lookup

child server의 직접 console.log 호출은 stdout/stderr pipe를 통해 저장됩니다. gateway process의 직접 console.log 호출은 Logger sink 캡처 대상이 아니므로 runtime code에서는 Logger 사용을 권장합니다.