Package Functions

DD provides a rich set of package-level functions callable directly via the dd. prefix. Logging functions execute through the global logger (Default()); the exception is the debug-output functions JSON/JSONF/Text/Textf/Exit/Exitf, which bypass the output targets configured in Config.Targets, write directly to os.Stdout, and do not go through security filtering.

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 (Debug level)
ProductionConfig	func ProductionConfig() Config	Production config (Info level, JSON format, RFC3339 timestamps)

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
Close	func Close() error	Close the global logger (after Close, package-level log functions become no-ops; prefer Shutdown in production code)
Shutdown	func Shutdown(ctx context.Context) error	Graceful shutdown with timeout

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 Deprecated	func DefaultSecureConfig() *SecurityConfig	Complete security config (a near-homonym of DefaultSecurityConfig with a different filtering strength, easy to confuse; use SecurityConfigForLevel(dd.SecurityLevelStandard) instead)
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
DefaultRateLimitConfig	func DefaultRateLimitConfig() *RateLimitConfig	Default rate-limit config (10,000 messages/s, 10MB/s, burst of 1,000 messages, drop strategy, 1-in-100 sampling rate; see Security Filtering)

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