12. 로깅

상세 SQL 추적 로그는 Java API의 trace 플래그와 Spring Boot 로그 레벨이 함께 맞아야 안정적으로 확인할 수 있다.

12.1 런타임 설정

서버 실행 시 JVM 옵션 또는 환경 변수를 통해 추적 로그를 활성화할 수 있다. 아래 방법 중 하나만 설정하면 된다.

1. JVM 옵션 설정

java -Daltibase.document.trace=true -jar document-access-rest-1.0.0.war

1. 환경 변수를 통한 설정

2. JAVA_TOOL_OPTIONS 사용

   # PowerShell (Windows)
   $env:JAVA_TOOL_OPTIONS="-Daltibase.document.trace=true"
   java -jar document-access-rest-1.0.0.war
   
   # Bash (Linux / macOS)
   export JAVA_TOOL_OPTIONS="-Daltibase.document.trace=true"
   java -jar document-access-rest-1.0.0.war
   

3. ALTIBASE_DOCUMENT_TRACE 사용

   # Bash (Linux / macOS)
   ALTIBASE_DOCUMENT_TRACE=true java -jar document-access-rest-1.0.0.war
   

4. Docker 환경에서의 설정

컨테이너 내부의 파일을 수정할 필요 없이 -e 옵션으로 모든 로깅 제어가 가능하다.

docker run -d \
  -e ALTIBASE_DOCUMENT_TRACE=true \
  -e LOGGING_LEVEL_COM_ALTIBASE_DOCUMENT=DEBUG \
  -p 8080:8080 \
  altibase-document-access:latest

12.2 애플리케이션 설정 (application.yml)

운영 기본 설정은 INFO이며, 상세 추적이 필요할 때만 com.altibase.document 를 DEBUG로 올리는 것을 권장한다.

logging:
  level:
    # 운영 기본값
    com.altibase.document: INFO
    com.altibase.document.rest: INFO

Docker 및 환경변수로 설정

application.yml 파일을 직접 수정하기 어려운 환경에서는 아래와 같은 환경 변수명을 사용하여 설정을 덮어쓸 수 있다. - 변수명: LOGGING_LEVEL_COM_ALTIBASE_DOCUMENT - 설정값: DEBUG 또는 TRACE

12.3. 로그 레벨 및 출력 내용

ALTIBASE_DOCUMENT_TRACE=true와 LOGGING_LEVEL_COM_ALTIBASE_DOCUMENT=DEBUG를 함께 설정하면 상세 SQL 및 메타데이터 호출 로그를 확인할 수 있다.

레벨	주요 출력 내용
INFO	기본적인 초기화 정보 및 연결 상태 (기본값)
DEBUG	실행되는 SQL, 메타데이터 호출, 상세 추적 로그
WARN / ERROR	경고 및 예외 로그

출력 예시

2026-02-12T14:00:39.828+09:00 DEBUG 17148 --- [nio-8080-exec-10] c.a.document.impl.AltibaseDatabaseImpl   : Creating table: CREATE TABLE "test01_MY_BOOKS"(_ID VARCHAR(40) PRIMARY KEY, ..., DOCUMENT JSON)
2026-02-12T14:00:39.910 DEBUG 17148 --- [nio-8080-exec-10] c.a.d.r.KadaCollectionMetadataRepository : Executing Call: { CALL kada_api_admin.dbms_kada.insert_metadata(?, ?, ...) }