log

package module
v0.0.0-...-4e3017e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 11, 2025 License: Apache-2.0 Imports: 21 Imported by: 76

README

log

A flexible and structured logging package for Golang applications in the Deckhouse ecosystem.

Overview

The log package provides a consistent logging interface for Deckhouse components. It builds upon Go's log/slog package to offer structured logging capabilities with additional features tailored for Kubernetes and cloud-native applications.

Features

  • Structured logging with key-value pairs
  • Multiple log levels (DEBUG, INFO, WARN, ERROR, FATAL)
  • Context-aware logging
  • Customizable output formats (JSON, text)
  • Integration with Kubernetes logging standards
  • Context propagation for distributed tracing

Installation

go get github.com/deckhouse/deckhouse/pkg/log

Basic Usage

package main

import (
    "context"
    
    "github.com/deckhouse/deckhouse/pkg/log"
)

func main() {
    // Get the default logger
    logger := log.Logger
    
    // Basic logging
    logger.Info("Application started")
    
    // Logging with key-value fields
    logger.Info("Processing request", 
        "requestID", "abc-123",
        "method", "GET",
        "path", "/api/v1/users",
    )
    
    // Logging with key-value slog attributes
    logger.Info("Processing request", 
        slog.String("requestID", "abc-123"),
        slog.String("method", "GET"),
        slog.String("path", "/api/v1/users"),
    )
    
    // Error logging
    err := someFunction()
    if err != nil {
        logger.Error("Failed to execute function", "error", err)
    }
    
    // Debug logging
    logger.Debug("Detailed operation information", 
        slog.String("operation", "database query"),
        slog.Uint64("duration_ms", 42),
    )
}

Creating Custom Loggers

package main

import (
    "os"
    "log/slog"
    
    "github.com/deckhouse/deckhouse/pkg/log"
)

func main() {
    // Create a logger with custom options
    customLogger := log.NewLogger(
        log.WithOutput(os.Stdout),
        log.WithLevel(slog.LevelDebug),
        log.WithHandlerType(log.JSONHandlerType),
    )
    
    // Use the custom logger
    customLogger.Info("Using custom logger")
    
    // Create a logger for a specific component
    moduleLogger := log.NewLogger().Named("logger-name")
    
    moduleLogger.Info("Controller initialized")
}

Log Levels

// Set global log level
log.SetDefaultLevel(log.LevelDebug)

// use global logger in variable
logger:= log.Default()

// Log at specific levels
logger.Debug("Debug information")
logger.Info("Informational message")
logger.Warn("Warning message")
logger.Error("Error message")
logger.Fatal("Fatal message")

// Check if a level would be logged
if logger.Enabled(context.TODO(), log.LevelDebug.Level()) {
    // Only prepare expensive debug data if it would be logged
    debugData := prepareExpensiveDebugData()
    logger.Debug("Expensive debug info", "data", debugData)
}

Best Practices

  1. Use structured logging: Always use key-value pairs instead of formatting strings

    // Good
logger.Info("User created", slog.Uint64("userID", user.ID), slog.String("role", user.Role))

// Avoid
logger.Info(fmt.Sprintf("User created: ID=%d, Role=%s", user.ID, user.Role))

  2. Use appropriate log levels:

    • Debug: Detailed information, useful for development and troubleshooting
    • Info: Confirmation that things are working as expected
    • Warn: Something unexpected happened, but the application can continue
    • Error: Something failed, but the application can still function

  3. Include context in logs:

    logger.Info("Processing complete", 
    slog.String("operation", "sync"),
    slog.String("resourceType", "deployment"),
    slog.String("namespace", "default"),
    slog.String("name", "my-app"),
    slog.Uint64("duration_ms", 235),
)

  4. Use with-style methods for adding context to loggers:

    controllerLogger := logger.With(
    slog.String("controller", "deployment"),
    slog.String("namespace", deployment.Namespace),
)

License

Apache 2.0

Documentation

Overview

global logger is deprecated

Index

Constants

View Source 
const (
	LoggerNameKey = "logger"
	StacktraceKey = "stacktrace"
)
View Source 
const KeyComponent = "component"

Variables

This section is empty.

Functions

func Debug 

func Debug(msg string, args ...any)

func DebugContext 

func DebugContext(ctx context.Context, msg string, args ...any)

func Debugf deprecated 

func Debugf(format string, args ...any)

Deprecated: use Debug instead

func Err 

func Err(err error) slog.Attr

func Error 

func Error(msg string, args ...any)

func ErrorContext 

func ErrorContext(ctx context.Context, msg string, args ...any)

func Errorf deprecated 

func Errorf(format string, args ...any)

Deprecated: use Error instead

func Fatal 

func Fatal(msg string, args ...any)

func FatalContext 

func FatalContext(ctx context.Context, msg string, args ...any)

func Fatalf deprecated 

func Fatalf(format string, args ...any)

Deprecated: use Fatal instead

func Info 

func Info(msg string, args ...any)

func InfoContext 

func InfoContext(ctx context.Context, msg string, args ...any)

func Infof deprecated 

func Infof(format string, args ...any)

Deprecated: use Info instead

func Log 

func Log(ctx context.Context, level Level, msg string, args ...any)

func LogAttrs 

func LogAttrs(ctx context.Context, level Level, msg string, attrs ...slog.Attr)

func Logf deprecated 

func Logf(ctx context.Context, level Level, format string, args ...any)

Deprecated: use Log instead

func RawJSON 

func RawJSON(key, text string) slog.Attr

func RawYAML 

func RawYAML(key, text string) slog.Attr

func SetDefault 

func SetDefault(l *Logger)

func SetDefaultLevel 

func SetDefaultLevel(l Level)

func Type 

func Type(key string, t any) slog.Attr

func Warn 

func Warn(msg string, args ...any)

func WarnContext 

func WarnContext(ctx context.Context, msg string, args ...any)

func Warnf deprecated 

func Warnf(format string, args ...any)

Deprecated: use Warn instead

Types

type AddSourceVar 

type AddSourceVar struct {
	// contains filtered or unexported fields
}

func (*AddSourceVar) Set 

func (v *AddSourceVar) Set(b bool)

func (*AddSourceVar) Source 

func (v *AddSourceVar) Source() *bool

func (*AddSourceVar) String 

func (v *AddSourceVar) String() string

type Handler 

type Handler interface {
	Enabled(context.Context, slog.Level) bool
	Handle(ctx context.Context, r slog.Record) error
	Named(name string) slog.Handler
	SetOutput(w io.Writer)
	WithAttrs(attrs []slog.Attr) slog.Handler
	WithGroup(name string) slog.Handler
}

type HandlerType 

type HandlerType int
const (
	JSONHandlerType HandlerType = iota
	TextHandlerType
)

type Level 

type Level slog.Level
const (
	LevelTrace Level = -8
	LevelDebug Level = -4
	LevelInfo  Level = 0
	LevelWarn  Level = 4
	LevelError Level = 8
	LevelFatal Level = 12
)

func LogLevelFromStr 

func LogLevelFromStr(rawLogLevel string) Level

func ParseLevel 

func ParseLevel(rawLogLevel string) (Level, error)

func (Level) Level 

func (l Level) Level() slog.Level

func (Level) String 

func (l Level) String() string

type LogOutput 

type LogOutput struct {
	Level      string         `json:"level"`
	Name       string         `json:"logger"`
	Message    string         `json:"msg"`
	Source     string         `json:"source"`
	Fields     map[string]any `json:"-"`
	Stacktrace string         `json:"stacktrace"`
	Time       string         `json:"time"`
}

func (*LogOutput) MarshalJSON 

func (lo *LogOutput) MarshalJSON() ([]byte, error)

func (*LogOutput) Text 

func (lo *LogOutput) Text() ([]byte, error)

type Logger 

type Logger struct {
	// contains filtered or unexported fields
}

func Default 

func Default() *Logger

func NewLogger 

func NewLogger(opts ...Option) *Logger

func NewNop 

func NewNop() *Logger

func (*Logger) Debugf deprecated 

func (l *Logger) Debugf(format string, args ...any)

Deprecated: use Debug instead

func (*Logger) Error 

func (l *Logger) Error(msg string, args ...any)

func (*Logger) Errorf deprecated 

func (l *Logger) Errorf(format string, args ...any)

Deprecated: use Error instead

func (*Logger) Fatal 

func (l *Logger) Fatal(msg string, args ...any)

func (*Logger) Fatalf deprecated 

func (l *Logger) Fatalf(format string, args ...any)

Deprecated: use Fatal instead

func (*Logger) GetLevel 

func (l *Logger) GetLevel() Level

func (*Logger) Infof deprecated 

func (l *Logger) Infof(format string, args ...any)

Deprecated: use Info instead

func (*Logger) Logf deprecated 

func (l *Logger) Logf(ctx context.Context, level Level, format string, args ...any)

Deprecated: use Log instead

func (*Logger) Named 

func (l *Logger) Named(name string) *Logger

func (*Logger) SetLevel 

func (l *Logger) SetLevel(level Level)

func (*Logger) SetOutput 

func (l *Logger) SetOutput(w io.Writer)

func (*Logger) Warnf deprecated 

func (l *Logger) Warnf(format string, args ...any)

Deprecated: use Warn instead

func (*Logger) With 

func (l *Logger) With(args ...any) *Logger

func (*Logger) WithGroup 

func (l *Logger) WithGroup(name string) *Logger

type Option 

type Option func(*Options)

func WithHandlerType 

func WithHandlerType(handlerType HandlerType) Option

WithHandlerType sets the handler type

func WithLevel 

func WithLevel(level slog.Level) Option

WithLevel sets the logging level

func WithOutput 

func WithOutput(output io.Writer) Option

WithOutput sets the output writer

func WithTimeFunc 

func WithTimeFunc(timeFunc func(t time.Time) time.Time) Option

WithTimeFunc sets the time function

type Options 

type Options struct {
	Level       slog.Level
	Output      io.Writer
	HandlerType HandlerType
	TimeFunc    func(t time.Time) time.Time
}

type Raw 

type Raw struct {
	// contains filtered or unexported fields
}

func NewJSONRaw 

func NewJSONRaw(text string) *Raw

made them public to use without slog.Attr

func NewYAMLRaw 

func NewYAMLRaw(text string) *Raw

func (*Raw) LogValue 

func (r *Raw) LogValue() slog.Value

type Render 

type Render struct {
	// contains filtered or unexported fields
}

func (*Render) FieldsToString 

func (r *Render) FieldsToString(m map[string]any, keyPrefix string)

func (*Render) JSONKeyValue 

func (r *Render) JSONKeyValue(key, value string)

func (*Render) RawJsonKeyValue 

func (r *Render) RawJsonKeyValue(key, value string)

func (*Render) TextKeyValue 

func (r *Render) TextKeyValue(key, value string)

func (*Render) TextQuotedKeyValue 

func (r *Render) TextQuotedKeyValue(key, value string)

type SlogJsonHandler 

type SlogJsonHandler struct {
	slog.Handler
	// contains filtered or unexported fields
}

func NewJSONHandler 

func NewJSONHandler(out io.Writer, opts *slog.HandlerOptions, timeFn func(t time.Time) time.Time) *SlogJsonHandler

func NewSlogHandler 

func NewSlogHandler(handler slog.Handler) *SlogJsonHandler

func (*SlogJsonHandler) Handle 

func (h *SlogJsonHandler) Handle(ctx context.Context, r slog.Record) error

func (*SlogJsonHandler) Named 

func (h *SlogJsonHandler) Named(name string) slog.Handler

func (*SlogJsonHandler) SetOutput 

func (h *SlogJsonHandler) SetOutput(w io.Writer)

func (*SlogJsonHandler) WithAttrs 

func (h *SlogJsonHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (*SlogJsonHandler) WithGroup 

func (h *SlogJsonHandler) WithGroup(name string) slog.Handler

type SlogTextHandler 

type SlogTextHandler struct {
	slog.Handler
	// contains filtered or unexported fields
}

func NewSlogTextHandler 

func NewSlogTextHandler(handler slog.Handler) *SlogTextHandler

func NewTextHandler 

func NewTextHandler(out io.Writer, opts *slog.HandlerOptions, timeFn func(t time.Time) time.Time) *SlogTextHandler

func (*SlogTextHandler) Handle 

func (h *SlogTextHandler) Handle(ctx context.Context, r slog.Record) error

func (*SlogTextHandler) Named 

func (h *SlogTextHandler) Named(name string) slog.Handler

func (*SlogTextHandler) SetOutput 

func (h *SlogTextHandler) SetOutput(w io.Writer)

func (*SlogTextHandler) WithAttrs 

func (h *SlogTextHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (*SlogTextHandler) WithGroup 

func (h *SlogTextHandler) WithGroup(name string) slog.Handler

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.