로그

로그 (Logs)

dbt는 로그를 CLI 콘솔과 로그 파일 두 곳에 출력해요. 이 페이지에서는 로그 형식, 로그 레벨, 출력 억제, 색상 설정 등 로그와 관련된 여러 글로벌 설정을 다뤄요.

출처: 문서

본문

로그 형식 (Log formatting)

dbt는 로그를 CLI 콘솔과 로그 파일 두 곳에 출력해요.

(dbt v2.0 이상) LOG_FORMAT과 LOG_FORMAT_FILE 설정은 dbt 로그의 형식을 지정해요. 공통 옵션은 text, json, default예요. otel 옵션은 LOG_FORMAT(콘솔 출력)에서만 사용할 수 있어요. --log-format-file otel를 설정해도 효과가 없어요. otel 형식은 OpenTelemetry 스타일의 구조화 텔레메트리를 콘솔로 스트리밍해요. dbt v1의 json 로그와는 다른 스키마를 사용해요. JSONL 파일, Parquet 내보내기, OTLP, 그리고 dbt v1 구조화 로깅과의 관계는 dbt v2 telemetry and observability 문서를 참고하세요.

Usage

dbt build --log-format otel

(dbt v2.0 이상) text 형식은 콘솔 로그의 기본값이며, 일반 텍스트 진행 메시지를 출력해요:

dbt 2.0.1
  Loading ~/.dbt/profiles.yml

json 형식은 완전히 구조화된 JSON 형식의 로그를 출력해요:

(dbt v2.0 이상)

{"data": {"log_version": 3, "version": "=2.0.0-preview.181"}, "info": {"category": "", "code": "A001", "extra": {}, "invocation_id": "019fb7d4-ce89-7712-8d06-5ad013a23be9", "level": "info", "msg": "Running with dbt-fusion=2.0.0-preview.181", "name": "MainReportVersion", "pid": 92554, "thread": "tokio-rt-worker", "ts": "2026-07-31T11:00:04.877509Z"}}
{"data": {"msg": "Loading ~/.dbt/profiles.yml"}, "info": {"category": "", "code": "", "extra": {}, "invocation_id": "019fb7d4-ce89-7712-8d06-5ad013a23be9", "level": "info", "msg": "Loading ~/.dbt/profiles.yml", "name": "Generic", "pid": 92554, "thread": "tokio-rt-worker", "ts": "2026-07-31T11:00:04.882928Z"}}

(dbt v2.0 이상) LOG_FORMAT이 명시적으로 text, json, default로 설정되면 콘솔과 로그 파일 양쪽에 적용돼요. otel 값은 콘솔 출력에만 적용돼요. 로그 파일에 다른 형식을 설정하려면 LOG_FORMAT_FILE을 사용해요 (text, json, default).

Usage

dbt run --log-format-file json

(dbt v2.0 이상) 팁: 구조화 관찰 — --log-format otel을 사용해 OpenTelemetry 스타일 텔레메트리를 콘솔로 스트리밍하거나, --otel-file-name 및 관련 플래그를 파일·플랫폼 통합에 사용할 수 있어요. dbt v2 telemetry and observability를 참고하세요. JSON 형식의 로그 줄에는 --log-format json과 DEBUG 설정을 사용해요:

dbt build --debug --log-format json

로그 레벨 (Log Level)

LOG_LEVEL 설정은 콘솔과 파일 로그에 캡처되는 이벤트의 최소 심각도를 설정해요. --debug 플래그보다 더 유연한 대안이에요. 사용 가능한 로그 레벨 옵션은 debug, info, warn, error, none이에요.

--log-level을 설정하면 콘솔과 파일 로그를 모두 구성해요.

dbt run --log-level debug

LOG_LEVEL을 none으로 설정하면 콘솔이나 파일 로그 어느 쪽으로도 정보가 전송되지 않아요.

dbt run --log-level none

파일 로그 레벨을 콘솔과 다르게 설정하려면 --log-level-file 플래그를 사용해요.

dbt run --log-level-file error

로그 파일 쓰기만 비활성화하고 콘솔 로그는 유지하려면 LOG_LEVEL_FILE 설정을 none으로 설정해요.

dbt run --log-level-file none

디버그 레벨 로깅 (Debug-level logging)

DEBUG 설정은 dbt의 디버그 로그를 표준 출력으로 리다이렉트해요. 이렇게 하면 logs/dbt.log 파일에 더해 터미널에도 디버그 레벨 로그 정보가 표시돼요. 이 출력은 매우 장황해요.

--debug 플래그는 -d 줄임말로도 사용할 수 있어요.

Usage

dbt run --debug

로그 및 타겟 경로 (Log and target paths)

기본적으로 dbt는 로그를 logs/라는 디렉터리에, 나머지 아티팩트는 target/이라는 디렉터리에 써요. 두 디렉터리 모두 활성 프로젝트의 dbt_project.yml 기준 상대 위치에 있어요.

다른 글로벌 설정과 마찬가지로, CLI 옵션(--target-path, --log-path) 또는 환경 변수((dbt v1.11 이상) DBT_ENGINE_TARGET_PATH, DBT_ENGINE_LOG_PATH)를 사용해 환경 또는 실행에 맞게 값을 덮어쓸 수 있어요.

출력에서 오류가 아닌 로그 억제 (Suppress non-error logs in output)

기본적으로 dbt는 모든 로그를 표준 출력(stdout)에 표시해요. QUIET 설정을 사용하면 stdout에 오류 로그만 표시하도록 할 수 있어요. 로그에는 print() 매크로에 전달된 모든 출력이 여전히 포함돼요. 예를 들어, 모든 로그를 억제하고 오류 로그만 남겨 Jinja 오류를 더 쉽게 찾고 디버깅할 수 있어요.

profiles.yml

config:
  quiet: true

dbt run에 -q 또는 --quiet 플래그를 주면 오류 로그만 표시하고 오류가 아닌 로그를 억제해요.

dbt run --quiet

dbt list 로깅 (dbt list logging)

dbt 버전 1.5에서 우리는 dbt list 명령의 로깅 동작을 업데이트해서 기본적으로 INFO 레벨 로그를 포함하도록 했어요.

결과를 jq, 파일 또는 다른 프로세스로 파이프하는 등 다운스트림 프로세스와 호환되는 깨끗한 출력을 원한다면 다음 매개변수 중 하나를 사용할 수 있어요:

  • dbt list --log-level warn (권장; 이전 기본값과 동일)
  • dbt list --quiet (ERROR 레벨보다 낮은 모든 로깅을 억제하며, "printed" 메시지와 list 출력은 제외)

관계형 캐시 이벤트 로깅 (Logging relational cache events)

LOG_CACHE_EVENTS 설정은 관계형 캐시에 대한 상세 로깅을 허용하며, 기본적으로 비활성화되어 있어요.

dbt compile --log-cache-events

색상 (Color)

파일 로그의 색상 기본 설정은 profiles.yml에서만 설정하거나 --use-colors-file / --no-use-colors-file 플래그를 사용해 설정할 수 있어요.

profiles.yml

config:
  use_colors_file: False

dbt run --use-colors-file
dbt run --no-use-colors-file

더 알아보기 (Learn more)