Package Functions

DD provides a rich set of package-level functions callable directly via the dd. prefix. All of them execute through the global logger (Default()).

Logger Creation

New

func New(cfg ...Config) (*Logger, error)

Creates a new Logger instance. Uses default settings when no config is provided.

// Default config
logger, _ := dd.New()

// Custom config
logger, _ := dd.New(dd.DefaultConfig())

// Note: only 0 or 1 config is accepted; passing multiple returns an error
// logger, _ := dd.New(cfg1, cfg2)  // Error!

Global Logger

Get and Set

Function	Signature	Description
`Default`	`func Default() *Logger`	Get the global logger (lazy-initialized)
`SetDefault`	`func SetDefault(logger *Logger)`	Set the global logger
`InitDefault`	`func InitDefault(cfg ...Config) error`	Initialize the global logger with config
`DefaultWithErr`	`func DefaultWithErr() (*Logger, error)`	Get the global logger and its initialization error
`DefaultInitError`	`func DefaultInitError() error`	Get the initialization error

Initialize the Global Logger

// Option 1: auto-initialize (created on first call)
dd.Default().Info("global logger auto-created")

// Option 2: explicit initialization
err := dd.InitDefault(dd.JSONConfig())
if err != nil {
    log.Fatal(err)
}
dd.Default().Info("global logger with JSON config")

// Option 3: replace the global logger
custom, _ := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{dd.FileOutput("logs/app.log")},
})
dd.SetDefault(custom)

// Option 4: check initialization errors
logger, err := dd.DefaultWithErr()
if err != nil {
    log.Printf("global logger initialization failed: %v", err)
}

Configuration Presets

Function	Signature	Description
`DefaultConfig`	`func DefaultConfig() Config`	Default config (Info level, text format)
`DevelopmentConfig`	`func DevelopmentConfig() Config`	Development config (Debug level)
`JSONConfig`	`func JSONConfig() Config`	JSON output config

cfg := dd.DefaultConfig()
cfg.Level = dd.LevelDebug
logger, _ := dd.New(cfg)

Output Target Constructors

Function	Signature	Description
`ConsoleOutput`	`func ConsoleOutput() OutputTarget`	Console output
`FileOutput`	`func FileOutput(path string) OutputTarget`	File output (supports rotation)
`CustomOutput`	`func CustomOutput(w io.Writer) OutputTarget`	Custom Writer output

cfg := dd.DefaultConfig()
cfg.Targets = []dd.OutputTarget{
    dd.ConsoleOutput(),
    dd.FileOutput("logs/app.log"),
    dd.CustomOutput(customWriter),
}
logger, _ := dd.New(cfg)

Basic Logging (Package-level)

The following functions emit logs through the global logger:

Function	Signature	Description
`Debug`	`func Debug(args ...any)`	Debug-level log
`Info`	`func Info(args ...any)`	Info-level log
`Warn`	`func Warn(args ...any)`	Warn-level log
`Error`	`func Error(args ...any)`	Error-level log
`Fatal`	`func Fatal(args ...any)`	Fatal-level log (by default calls os.Exit(1), deferred functions will not run; customizable via FatalHandler)

dd.Info("application started")
dd.Errorf("user %s login failed", username)
dd.Warn("low disk space")

Formatted Logging (Package-level)

Function	Signature	Description
`Debugf`	`func Debugf(format string, args ...any)`	Debug-level formatted log
`Infof`	`func Infof(format string, args ...any)`	Info-level formatted log
`Warnf`	`func Warnf(format string, args ...any)`	Warn-level formatted log
`Errorf`	`func Errorf(format string, args ...any)`	Error-level formatted log
`Fatalf`	`func Fatalf(format string, args ...any)`	Fatal-level formatted log (by default calls os.Exit(1), deferred functions will not run; customizable via FatalHandler)

Generic-Level Logging (Package-level)

Function	Signature	Description
`Log`	`func Log(level LogLevel, args ...any)`	Specified-level log
`Logf`	`func Logf(level LogLevel, format string, args ...any)`	Specified-level formatted log
`LogWith`	`func LogWith(level LogLevel, msg string, fields ...Field)`	Specified-level structured log

dd.Log(dd.LevelDebug, "debug message")
dd.Logf(dd.LevelWarn, "warning: %s", reason)
dd.LogWith(dd.LevelError, "request failed",
    dd.String("path", "/api/users"),
    dd.Int("status", 500),
)

Structured Logging (Package-level)

The following functions emit structured logs through the global logger:

Function	Signature	Description
`DebugWith`	`func DebugWith(msg string, fields ...Field)`	Debug-level structured log
`InfoWith`	`func InfoWith(msg string, fields ...Field)`	Info-level structured log
`WarnWith`	`func WarnWith(msg string, fields ...Field)`	Warn-level structured log
`ErrorWith`	`func ErrorWith(msg string, fields ...Field)`	Error-level structured log
`FatalWith`	`func FatalWith(msg string, fields ...Field)`	Fatal-level structured log (by default calls os.Exit(1), deferred functions will not run; customizable via FatalHandler)

dd.InfoWith("request completed",
    dd.String("method", "GET"),
    dd.Int("status", 200),
)

dd.ErrorWith("database error",
    dd.Err(err),
    dd.String("query", sql),
)

Level Management (Package-level)

Function	Signature	Description
`SetLevel`	`func SetLevel(level LogLevel) error`	Set the global log level
`GetLevel`	`func GetLevel() LogLevel`	Get the global log level
`IsLevelEnabled`	`func IsLevelEnabled(level LogLevel) bool`	Check whether a level is enabled
`IsDebugEnabled`	`func IsDebugEnabled() bool`	Check whether Debug level is enabled
`IsInfoEnabled`	`func IsInfoEnabled() bool`	Check whether Info level is enabled
`IsWarnEnabled`	`func IsWarnEnabled() bool`	Check whether Warn level is enabled
`IsErrorEnabled`	`func IsErrorEnabled() bool`	Check whether Error level is enabled
`IsFatalEnabled`	`func IsFatalEnabled() bool`	Check whether Fatal level is enabled

// Dynamically adjust the log level
dd.SetLevel(dd.LevelDebug)

// Conditional logging (avoid unnecessary computation)
if dd.IsDebugEnabled() {
    dd.Debug(computeExpensiveDebugInfo())
}

Field Chaining (Package-level)

Function	Signature	Description
`WithFields`	`func WithFields(fields ...Field) *LoggerEntry`	Create an Entry with preset fields
`WithField`	`func WithField(key string, value any) *LoggerEntry`	Create an Entry with a single preset field

dd.WithFields(dd.String("service", "api"), dd.String("version", "1.0")).
    Info("request completed")

dd.WithField("request_id", "abc123").Info("processing request")

Lifecycle (Package-level)

Function	Signature	Description
`Flush`	`func Flush() error`	Flush the global logger buffers

Writer Management (Package-level)

Function	Signature	Description
`AddWriter`	`func AddWriter(writer io.Writer) error`	Add an output writer
`RemoveWriter`	`func RemoveWriter(writer io.Writer) error`	Remove an output writer
`WriterCount`	`func WriterCount() int`	Get the writer count

Sampling Control (Package-level)

Function	Signature	Description
`SetSampling`	`func SetSampling(config *SamplingConfig)`	Set sampling config
`GetSampling`	`func GetSampling() *SamplingConfig`	Get sampling config

Writer Constructors

Function	Signature	Description
`NewFileWriter`	`func NewFileWriter(path string, cfg FileWriterConfig) (*FileWriter, error)`	Create a file writer
`DefaultFileWriterConfig`	`func DefaultFileWriterConfig() FileWriterConfig`	Default file writer config
`NewBufferedWriter`	`func NewBufferedWriter(w io.Writer, cfg BufferedWriterConfig) (*BufferedWriter, error)`	Create a buffered writer
`DefaultBufferedWriterConfig`	`func DefaultBufferedWriterConfig() BufferedWriterConfig`	Default buffered writer config
`NewMultiWriter`	`func NewMultiWriter(writers ...io.Writer) *MultiWriter`	Create a multi-output writer

Security Config Constructors

Function	Signature	Description
`DefaultSecurityConfig`	`func DefaultSecurityConfig() *SecurityConfig`	Default security config (basic filtering)
`DefaultSecureConfig`	`func DefaultSecureConfig() *SecurityConfig`	Complete security config
`HealthcareConfig`	`func HealthcareConfig() *SecurityConfig`	HIPAA-compliant config
`FinancialConfig`	`func FinancialConfig() *SecurityConfig`	PCI-DSS-compliant config
`GovernmentConfig`	`func GovernmentConfig() *SecurityConfig`	Government-standard config
`SecurityConfigForLevel`	`func SecurityConfigForLevel(level SecurityLevel) *SecurityConfig`	Get security config by level

Sensitive-Data Filter Constructors

Function	Signature	Description
`NewSensitiveDataFilter`	`func NewSensitiveDataFilter() *SensitiveDataFilter`	Full pattern set filter
`NewEmptySensitiveDataFilter`	`func NewEmptySensitiveDataFilter() *SensitiveDataFilter`	Empty filter
`NewCustomSensitiveDataFilter`	`func NewCustomSensitiveDataFilter(patterns ...string) (*SensitiveDataFilter, error)`	Custom-pattern filter

Hook Constructors

Function	Signature	Description
`NewHookRegistry`	`func NewHookRegistry() *HookRegistry`	Create a hook registry
`NewHooksFromConfig`	`func NewHooksFromConfig(cfg HooksConfig) *HookRegistry`	Create a hook registry from config

Audit Logger Constructors

Function	Signature	Description
`NewAuditLogger`	`func NewAuditLogger(cfg AuditConfig) (*AuditLogger, error)`	Create an audit logger
`DefaultAuditConfig`	`func DefaultAuditConfig() AuditConfig`	Default audit config
`VerifyAuditEvent`	`func VerifyAuditEvent(entry string, signer IntegritySigner) AuditVerificationResult`	Verify the integrity of an audit event

Integrity Signing Constructors

Function	Signature	Description
`NewIntegritySigner`	`func NewIntegritySigner(cfg IntegrityConfig) (*IntegritySigner, error)`	Create an integrity signer
`DefaultIntegrityConfigSafe`	`func DefaultIntegrityConfigSafe() (IntegrityConfig, error)`	Safe random-key config

Test Helper Constructor

Function	Signature	Description
`NewLoggerRecorder`	`func NewLoggerRecorder() *LoggerRecorder`	Create a log recorder (for testing)

Context Functions

Function	Signature	Description
`WithTraceID`	`func WithTraceID(ctx context.Context, traceID string) context.Context`	Set Trace ID
`WithSpanID`	`func WithSpanID(ctx context.Context, spanID string) context.Context`	Set Span ID
`WithRequestID`	`func WithRequestID(ctx context.Context, requestID string) context.Context`	Set Request ID
`GetTraceID`	`func GetTraceID(ctx context.Context) string`	Get Trace ID
`GetSpanID`	`func GetSpanID(ctx context.Context) string`	Get Span ID
`GetRequestID`	`func GetRequestID(ctx context.Context) string`	Get Request ID

JSON Configuration

Function	Signature	Description
`DefaultJSONOptions`	`func DefaultJSONOptions() *JSONOptions`	Default JSON output options

Field Constructors

Used to create structured log fields (Field); used with the *With family of methods or WithFields.

Function	Signature	Description
`Any`	`func Any(key string, value any) Field`	Any-type field
`String`	`func String(key, value string) Field`	String field
`Bool`	`func Bool(key string, value bool) Field`	Bool field
`Int`	`func Int(key string, value int) Field`	int field
`Int8`	`func Int8(key string, value int8) Field`	int8 field
`Int16`	`func Int16(key string, value int16) Field`	int16 field
`Int32`	`func Int32(key string, value int32) Field`	int32 field
`Int64`	`func Int64(key string, value int64) Field`	int64 field
`Uint`	`func Uint(key string, value uint) Field`	uint field
`Uint8`	`func Uint8(key string, value uint8) Field`	uint8 field
`Uint16`	`func Uint16(key string, value uint16) Field`	uint16 field
`Uint32`	`func Uint32(key string, value uint32) Field`	uint32 field
`Uint64`	`func Uint64(key string, value uint64) Field`	uint64 field
`Float32`	`func Float32(key string, value float32) Field`	float32 field
`Float64`	`func Float64(key string, value float64) Field`	float64 field
`Duration`	`func Duration(key string, value time.Duration) Field`	Duration field
`Time`	`func Time(key string, value time.Time) Field`	Time field
`Err`	`func Err(err error) Field`	Error field (key is "error")
`ErrWithKey`	`func ErrWithKey(key string, err error) Field`	Error field with custom key
`ErrWithStack`	`func ErrWithStack(err error) Field`	Error field with stack trace

dd.InfoWith("request completed",
    dd.String("method", "GET"),
    dd.Int("status", 200),
    dd.Duration("elapsed", 100*time.Millisecond),
    dd.Err(err),
)

Type-safety recommendation

Prefer type-specific constructors (e.g. Int, String) over Any to catch type errors at compile time and avoid runtime issues from type mismatches.

Field Validation Configuration

Function	Signature	Description
`DefaultFieldValidationConfig`	`func DefaultFieldValidationConfig() *FieldValidationConfig`	Default field validation (none)
`StrictSnakeCaseConfig`	`func StrictSnakeCaseConfig() *FieldValidationConfig`	Strict snake_case validation
`StrictCamelCaseConfig`	`func StrictCamelCaseConfig() *FieldValidationConfig`	Strict camelCase validation

Debug Output Functions

Function	Signature	Description
`Print`	`func Print(args ...any)`	Output to the global logger's Writer (LevelInfo, subject to security filtering)
`Println`	`func Println(args ...any)`	Same as Print (the underlying Log() already appends a newline; subject to security filtering)
`Printf`	`func Printf(format string, args ...any)`	Formatted output (LevelInfo, subject to security filtering)
`JSON`	`func JSON(data ...any)`	Compact-JSON output to stdout (includes caller info; does not go through security filtering)
`JSONF`	`func JSONF(format string, args ...any)`	Formatted string output as compact JSON to stdout (includes caller info; does not go through security filtering)
`Text`	`func Text(data ...any)`	Pretty-printed output to stdout (does not go through security filtering)
`Textf`	`func Textf(format string, args ...any)`	Formatted text output to stdout (does not go through security filtering)
`Exit`	`func Exit(data ...any)`	Text output with caller info followed by exit (exit code 0); complex types are pretty-printed automatically; does not go through security filtering
`Exitf`	`func Exitf(format string, args ...any)`	Formatted output with caller info followed by exit (exit code 0; does not go through security filtering)

Debug-function security note

Print/Println/Printf go through security filtering, but JSON/JSONF/Text/Textf/Exit/Exitf emit raw data directly and do not go through security filtering.

Next Steps

Logger -- Logger instance methods in depth
LoggerEntry -- Log Entry with preset fields
Config -- Config struct
Debug Output -- Debug visual functions

Package Functions ​

Logger Creation ​

New ​

Global Logger ​

Get and Set ​

Initialize the Global Logger ​

Configuration Presets ​

Output Target Constructors ​

Basic Logging (Package-level) ​

Formatted Logging (Package-level) ​

Generic-Level Logging (Package-level) ​

Structured Logging (Package-level) ​

Level Management (Package-level) ​

Field Chaining (Package-level) ​

Lifecycle (Package-level) ​

Writer Management (Package-level) ​

Sampling Control (Package-level) ​

Writer Constructors ​

Security Config Constructors ​

Sensitive-Data Filter Constructors ​

Hook Constructors ​

Audit Logger Constructors ​

Integrity Signing Constructors ​

Test Helper Constructor ​

Context Functions ​

JSON Configuration ​

Field Constructors ​

Field Validation Configuration ​

Debug Output Functions ​

Next Steps ​