LoggerEntry

LoggerEntry는 사전 설정 필드를 가진 로거로, 최소 한 개의 필드를 전달하면 새로운 불변 Entry 를 반환합니다.

생성

// Logger 에서 생성
entry := logger.WithFields(
    dd.String("service", "api"),
    dd.String("env", "prod"),
)

// 전역 Logger 에서 생성
entry := dd.Default().WithFields(
    dd.String("service", "api"),
)

// 단일 필드 바로 가기
entry := logger.WithField("request_id", "req-123")

체인 호출

// 필드 추가 (새 Entry 반환, 원본 Entry 는 불변)
base := logger.WithFields(dd.String("svc", "api"))
enhanced := base.WithFields(dd.String("env", "prod"))

// 새 필드는 같은 이름의 이전 필드를 덮어씀
entry := base.WithField("svc", "gateway")  // svc 가 "gateway"로 변경

팁 불변성

최소 한 개의 필드를 전달하면 WithFields / WithField 호출은 새로운 LoggerEntry를 반환하며, 원본 Entry 는 영향을 받지 않아 안전하게 동시에 사용할 수 있습니다. WithFields()에 필드를 전달하지 않는 것은 무효 연산 최적화로, 원래 Entry 를 그대로 반환합니다.

로그 메서드

모든 Logger 의 로그 메서드는 Entry 에서도 사용할 수 있으며, 출력 로그에 자동으로 사전 설정 필드가 포함됩니다.

기본 로그

메서드	설명
Debug(args ...any)	Debug 레벨
Info(args ...any)	Info 레벨
Warn(args ...any)	Warn 레벨
Error(args ...any)	Error 레벨
Fatal(args ...any)	Fatal 레벨 (기본적으로 os.Exit(1) 호출, defer 는 실행되지 않음; FatalHandler 로 사용자 정의 가능)
Log(level LogLevel, args ...any)	레벨 지정

포맷팅 로그

메서드	설명
Debugf(format string, args ...any)	포맷팅 Debug
Infof(format string, args ...any)	포맷팅 Info
Warnf(format string, args ...any)	포맷팅 Warn
Errorf(format string, args ...any)	포맷팅 Error
Fatalf(format string, args ...any)	포맷팅 Fatal(기본적으로 os.Exit(1) 호출, defer 는 실행되지 않음; FatalHandler 로 사용자 정의 가능)
Logf(level LogLevel, format string, args ...any)	지정 레벨 포맷팅

구조화 로그

메서드	설명
DebugWith(msg string, fields ...Field)	구조화 Debug(사전 설정 필드와 병합)
InfoWith(msg string, fields ...Field)	구조화 Info
WarnWith(msg string, fields ...Field)	구조화 Warn
ErrorWith(msg string, fields ...Field)	구조화 Error
FatalWith(msg string, fields ...Field)	구조화 Fatal(기본적으로 os.Exit(1) 호출, defer 는 실행되지 않음; FatalHandler 로 사용자 정의 가능)
LogWith(level LogLevel, msg string, fields ...Field)	구조화 지정 레벨

Print 메서드

메서드	설명
Print(args ...any)	Writer 로 출력 (LevelInfo, 보안 필터 적용)
Println(args ...any)	Print 와 동일 동작
Printf(format string, args ...any)	포맷팅 출력 (LevelInfo, 보안 필터 적용)

필드 체인

메서드	설명
WithFields(fields ...Field) *LoggerEntry	필드 추가, 새 Entry 반환
WithField(key string, value any) *LoggerEntry	단일 필드 추가, 새 Entry 반환

사용 예

HTTP 요청 로그

func handleRequest(w http.ResponseWriter, r *http.Request) {
    reqLog := logger.WithFields(
        dd.String("method", r.Method),
        dd.String("path", r.URL.Path),
        dd.String("remote", r.RemoteAddr),
    )

    reqLog.Info("요청 시작")

    // 처리 로직...

    reqLog.WithField("status", 200).Info("요청 완료")
}

서비스 컴포넌트 로그

serviceLog := logger.WithFields(
    dd.String("service", "user-service"),
    dd.String("version", "2.1.0"),
)

serviceLog.Info("서비스 시작")

dbLog := serviceLog.WithField("component", "database")
dbLog.Info("연결 성공")
dbLog.ErrorWith("쿼리 실패", dd.Err(err))

다음 단계

• Logger -- Logger 인스턴스 메서드
• 구조화 필드 -- Field 생성자
• 패키지 함수 -- 전역 로그 함수