log

package module
v0.0.0-...-6f62fc4 Latest Latest
Warning

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

Go to latest
Published: Jul 10, 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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL