설정

DD 는 Config 구조체로 로거의 동작을 구성하며, 여러 사전 설정 팩토리 함수를 제공합니다.

사전 설정 팩토리

// 기본 구성: INFO 레벨, 텍스트 형식
cfg := dd.DefaultConfig()

// 개발 구성: DEBUG 레벨, 동적 caller 감지
cfgDev := dd.DevelopmentConfig()

// JSON 구성: JSON 형식 출력
cfgJSON := dd.JSONConfig()

팩토리 함수	반환 타입	레벨	형식	적용 시나리오
DefaultConfig()	Config	Info	Text	프로덕션 환경
DevelopmentConfig()	Config	Debug	Text	개발 환경
JSONConfig()	Config	Debug	JSON	로그 수집

팁 보안 필터 기본 활성화

모든 사전 설정 구성 (DefaultConfig, DevelopmentConfig, JSONConfig) 은 기본적으로 보안 필터가 활성화되어, 비밀번호, API Key, 신용카드 번호 등 민감 데이터를 자동으로 마스킹합니다.

Config 구조체

type Config struct {
    // 로그 레벨
    Level          LogLevel         // 로그 레벨 (기본 LevelInfo)
    Format         LogFormat        // 출력 형식 (FormatText / FormatJSON)

    // 시간 구성
    TimeFormat     string           // 시간 형식 (기본 ISO 8601)
    IncludeTime    bool             // 시간 포함 여부 (기본 true)
    IncludeLevel   bool             // 레벨 포함 여부 (기본 true)

    // caller 정보
    DynamicCaller  bool             // 동적 caller 감지 (기본 true)
    FullPath       bool             // 전체 경로 표시 여부 (기본 false)

    // 출력 대상
    Targets        []OutputTarget   // 출력 대상 목록

    // JSON 구성
    JSON           *JSONOptions     // JSON 출력 옵션

    // 보안 구성
    Security       *SecurityConfig  // 보안 구성

    // 필드 검증
    FieldValidation *FieldValidationConfig

    // 라이프사이클 핸들러
    FatalHandler      FatalHandler       // Fatal 레벨 커스텀 처리 함수
    WriteErrorHandler WriteErrorHandler  // 쓰기 오류 콜백

    // 확장성
    ContextExtractors []ContextExtractor // 컨텍스트 추출기 목록
    Hooks             *HookRegistry      // 훅 레지스트리
    Sampling          *SamplingConfig    // 샘플링 구성

    // 감사 구성
    Audit             *AuditConfig       // 감사 로그 구성 (보안 이벤트 기록)
}

팁 Audit 필드

Audit를 설정하면 민감 데이터 마스킹, 속도 제한, 위반 이벤트가 AuditLogger를 통해 감사 이벤트로 기록됩니다. 자세한 내용은 감사 로그를 참고하세요.

Clone

func (c *Config) Clone() Config

구성의 복사본을 생성하여, 원본 구성에 영향을 주지 않고 안전하게 수정할 수 있습니다. nil 리시버에는 제로값 Config{}를 반환합니다.

복사 전략 (소스 코드 Clone 주석과 일치):

• 딥 카피: Targets(슬라이스), JSON(JSONFieldNames 포함), Security, Hooks, Sampling, Audit
• 얕은 카피: FatalHandler, WriteErrorHandler, FieldValidation(함수/포인터 공유)
• 혼합: ContextExtractors 슬라이스는 복사되지만 추출기 인스턴스 자체는 공유

base := dd.DefaultConfig()
custom := base.Clone()
custom.Level = dd.LevelDebug

Validate

func (c Config) Validate() error

구성의 유효성을 검사하고 처음 발견한 오류를 반환합니다. dd.New(cfg) 내부에서 자동으로 호출되며, New에 전달하기 전에 미리 호출해 문제를 발견할 수도 있습니다.

검사 항목:

• Level은 [LevelDebug, LevelFatal] 범위 내여야 함
• Format은 FormatText 또는 FormatJSON이어야 함
• IncludeTime=true이고 TimeFormat이 비어 있지 않을 때 Go 시간 레퍼런스 레이아웃 검증 (예: time.RFC3339)
• Targets 총수는 100 이하 (초과 시 ErrMaxWritersExceeded 반환)
• 각 Targets 요소: OutputCustom은 nil 이 아닌 Writer가 필요, OutputFile은 비어 있지 않은 Path가 필요

cfg := dd.DefaultConfig()
cfg.Level = dd.LevelDebug
if err := cfg.Validate(); err != nil {
    log.Fatal(err)
}

출력 대상

OutputType

출력 대상 유형 열거.

type OutputType int

상수	값	설명
OutputConsole	0	콘솔 출력 (stdout)
OutputFile	1	파일 출력
OutputCustom	2	사용자 정의 Writer

OutputTarget

출력 대상 구성, 단일 출력 대상을 기술.

type OutputTarget struct {
    Type       OutputType     // 출력 유형
    Path       string         // 파일 경로 (OutputFile 일 때 유효)
    MaxSizeMB  int            // 파일 크기 상한 MB(OutputFile 일 때 유효)
    MaxBackups int            // 보존 백업 수 (OutputFile 일 때 유효)
    MaxAge     time.Duration  // 이전 파일 보존 기간 (OutputFile 일 때 유효)
    Compress   bool           // gzip 압축 여부 (OutputFile 일 때 유효)
    Writer     io.Writer      // 사용자 정의 Writer(OutputCustom 일 때 유효)
}

출력 대상 생성자

func ConsoleOutput() OutputTarget
func FileOutput(path string) OutputTarget
func CustomOutput(w io.Writer) OutputTarget

팁 FileOutput 기본 로테이션 매개변수

FileOutput이 반환하는 OutputTarget은 기본 로테이션 값이 미리 채워져 있습니다: MaxSizeMB=100, MaxBackups=10, MaxAge=30 * 24 * time.Hour(30 일), Compress=false. 커스터마이징이 필요하면 반환값의 해당 필드를 직접 수정하세요.

target := dd.FileOutput("logs/app.log")
target.MaxSizeMB = 50               // 50MB 분할
target.MaxBackups = 5               // 백업 5 개 보존
target.MaxAge = 7 * 24 * time.Hour  // 7 일 보존
target.Compress = true              // 오래된 로그 gzip 압축

// 콘솔 출력
cfg.Targets = []dd.OutputTarget{dd.ConsoleOutput()}

// 파일 출력
cfg.Targets = []dd.OutputTarget{dd.FileOutput("logs/app.log")}

// 사용자 정의 Writer
cfg.Targets = []dd.OutputTarget{dd.CustomOutput(customWriter)}

// 다중 대상 출력
cfg.Targets = []dd.OutputTarget{
    dd.ConsoleOutput(),
    dd.FileOutput("logs/app.log"),
}

JSON 구성 옵션

JSONOptions

JSON 출력 형식 구성.

type JSONOptions struct {
    PrettyPrint bool           // 출력 보기 좋게 여부 (기본 false)
    Indent      string         // 들여쓰기 문자열 (기본 "  ")
    FieldNames  *JSONFieldNames // 커스텀 JSON 필드명
}

JSONFieldNames

JSON 출력에서의 필드명을 사용자 정의합니다. 다양한 로그 수집 시스템에 맞출 때 사용합니다.

type JSONFieldNames struct {
    Timestamp string  // 타임스탬프 필드명 (기본 "timestamp")
    Level     string  // 레벨 필드명 (기본 "level")
    Caller    string  // caller 필드명 (기본 "caller")
    Message   string  // 메시지 필드명 (기본 "message")
    Fields    string  // 필드 컨테이너명 (기본 "fields")
}

포인터 리시버 메서드 (*JSONFieldNames).IsComplete() bool을 구현합니다: 5 개 필드명이 모두 비어 있지 않을 때 true를 반환하며, 모든 필드명을 완전히 커스텀했는지 검증하는 데 사용할 수 있습니다.

사용 예:

cfg := dd.DefaultJSONOptions()
cfg.FieldNames = &dd.JSONFieldNames{
    Timestamp: "ts",
    Level:     "lvl",
    Message:   "msg",
}

DefaultJSONOptions

func DefaultJSONOptions() *JSONOptions

기본 JSONOptions 출력 옵션을 반환합니다: 기본적으로 보기 좋게 출력하지 않고 (들여쓰기 두 칸), 필드명은 기본값을 사용합니다.

opts := dd.DefaultJSONOptions()
opts.PrettyPrint = true

logger, _ := dd.New(dd.Config{
    Format: dd.FormatJSON,
    JSON:   opts,
})

SamplingConfig

샘플링 구성, 고처리량 시나리오에서 로그량을 줄이는 데 사용합니다.

type SamplingConfig struct {
    Enabled    bool          // 샘플링 활성화 여부
    Initial    int           // 샘플링 전까지 항상 기록하는 메시지 수
    Thereafter int           // 샘플링 비율 (값이 10 이면 10 개당 1 개 기록)
    Tick       time.Duration // 카운터 리셋 간격 (0 은 리셋 안 함)
}

cfg := dd.DefaultConfig()
cfg.Sampling = &dd.SamplingConfig{
    Enabled:    true,
    Initial:    100,
    Thereafter: 10,
    Tick:       time.Minute,
}
logger, _ := dd.New(cfg)

FieldValidationConfig

필드 검증 구성, 필드 키 이름의 명명 규칙을 제어합니다.

type FieldValidationConfig struct {
    Mode                     FieldValidationMode      // 검증 모드
    Convention               FieldNamingConvention    // 명명 규칙
    AllowCommonAbbreviations bool                      // 일반 약어 허용 (ID, URL 등)
    EnableSecurityValidation bool                      // 보안 검증 활성화 (Log4Shell, 동형자 (Homograph) 공격 등)
}

FieldValidationMode

상수	설명
FieldValidationNone	검증 비활성화 (기본)
FieldValidationWarn	규칙에 맞지 않는 필드를 경고하되 여전히 수락
FieldValidationStrict	명명이 일치하지 않을 때 stderr 에 오류 출력 (로그 항목은 정상적으로 기록되며 거부되지 않음)

String() 메서드를 구현하여 모드 이름을 반환합니다.

FieldNamingConvention

상수	설명	예
NamingConventionAny	모든 형식 수락 (기본)	-
NamingConventionSnakeCase	snake_case	user_id, created_at
NamingConventionCamelCase	camelCase	userId, createdAt
NamingConventionPascalCase	PascalCase	UserId, CreatedAt
NamingConventionKebabCase	kebab-case	user-id, created-at

String() 메서드를 구현하여 명명 규칙 이름을 반환합니다.

ValidateFieldKey

func (c *FieldValidationConfig) ValidateFieldKey(key string) error

필드 키 이름이 구성된 명명 규칙에 부합하는지 검증합니다.

필드 검증 구성

DefaultFieldValidationConfig

func DefaultFieldValidationConfig() *FieldValidationConfig

기본 구성: 검증 비활성화.

StrictSnakeCaseConfig

func StrictSnakeCaseConfig() *FieldValidationConfig

엄격한 snake_case 검증, 필드명은 snake_case 형식이어야 합니다.

StrictCamelCaseConfig

func StrictCamelCaseConfig() *FieldValidationConfig

엄격한 camelCase 검증, 필드명은 camelCase 형식이어야 합니다.

사용 방식

logger, _ := dd.New(dd.Config{
    Level:           dd.LevelInfo,
    FieldValidation: dd.StrictSnakeCaseConfig(),
})

// 유효
logger.InfoWith("ok", dd.String("user_name", "admin"))

// 명명 규칙 위반 (snake_case 가 아님, 로그는 여전히 기록되며 오류는 stderr 로 출력)
logger.InfoWith("fail", dd.String("userName", "admin"))

구성 예

프로덕션 환경

logger, _ := dd.New(dd.Config{
    Level:  dd.LevelInfo,
    Format: dd.FormatJSON,
    Targets: []dd.OutputTarget{
        dd.ConsoleOutput(),
        dd.FileOutput("logs/app.log"),
    },
    Security: dd.DefaultSecurityConfig(),
})

개발 환경

logger, _ := dd.New(dd.DevelopmentConfig())

다중 출력 대상

logger, _ := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{
        dd.ConsoleOutput(),
        dd.FileOutput("logs/app.log"),
    },
})

다음 단계

• Logger -- 구성으로 로거 생성
• 출력 대상 -- FileWriter, BufferedWriter, MultiWriter
• 보안 필터 -- SecurityConfig 상세
• 훅 시스템 -- HooksConfig 상세
• 감사 로그 -- AuditConfig 상세