logs

Documentation

Overview

Package logs provides structured logging utilities for Deputy.

This package builds on the standard library's log/slog package, providing a preconfigured logger with support for text and JSON output, colored terminal output, and OpenTelemetry trace context injection.

Creating a Logger

Use New to create a configured logger:

logger := logs.New(logs.Options{
    Level:        slog.LevelInfo,
    Format:       "text",
    Writer:       os.Stderr,
    ColorEnabled: true,
})
slog.SetDefault(logger)

Log Levels

Parse log levels from strings:

level, err := logs.ParseLevel("debug")  // Returns slog.LevelDebug
level, err := logs.ParseLevel("info")   // Returns slog.LevelInfo
level, err := logs.ParseLevel("warn")   // Returns slog.LevelWarn
level, err := logs.ParseLevel("error")  // Returns slog.LevelError

Output Formats

Two output formats are supported:

• "text": Human-readable format with optional colors
• "json": Structured JSON for log aggregation systems

Trace Context

When OpenTelemetry is enabled, trace context is automatically included:

logger := logs.New(logs.Options{
    IncludeTraceContext: true,
    ExportToOTel:        true,
})

This adds trace_id and span_id to log entries for correlation.

Default Logger

A package-level default logger is available:

logs.SetDefault(logger)
logs.Default().Info("message", "key", "value")

Package logs provides context-aware structured logging for Deputy using slog. It supports attaching loggers to contexts, optional ANSI color formatting, and consistent logging patterns across the codebase.

Index

• func Debug(ctx context.Context, msg string, args ...any)
• func Error(ctx context.Context, msg string, args ...any)
• func FromContext(ctx context.Context) *slog.Logger
• func Info(ctx context.Context, msg string, args ...any)
• func New(opts Options) *slog.Logger
• func ParseLevel(s string) (slog.Level, error)
• func SetDefault(logger *slog.Logger)
• func Warn(ctx context.Context, msg string, args ...any)
• func WithContext(ctx context.Context, logger *slog.Logger) context.Context
• func WithField(ctx context.Context, key string, value any) context.Context
• func WithFields(ctx context.Context, fields map[string]any) context.Context
• type ColorHandler
  • func NewColorHandler(w io.Writer, opts *slog.HandlerOptions) *ColorHandler
  • func (h *ColorHandler) Enabled(ctx context.Context, level slog.Level) bool
  • func (h *ColorHandler) Handle(ctx context.Context, r slog.Record) error
  • func (h *ColorHandler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *ColorHandler) WithGroup(name string) slog.Handler
• type Options

Functions

func Debug

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

Debug logs at Debug level using the logger from the context.

func Error

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

Error logs at Error level using the logger from the context.

func FromContext

func FromContext(ctx context.Context) *slog.Logger

FromContext extracts the logger from the context, returning the default logger if none is found.

func Info

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

Info logs at Info level using the logger from the context.

func New

func New(opts Options) *slog.Logger

New creates a new configured slog.Logger based on the provided options.

func ParseLevel

func ParseLevel(s string) (slog.Level, error)

ParseLevel converts a string level name to slog.Level.

func SetDefault

func SetDefault(logger *slog.Logger)

SetDefault sets the default logger used when no logger is attached to a context.

func Warn

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

Warn logs at Warn level using the logger from the context.

func WithContext

func WithContext(ctx context.Context, logger *slog.Logger) context.Context

WithContext returns a new context with the logger attached.

func WithField

func WithField(ctx context.Context, key string, value any) context.Context

WithField returns a new context with a logger that includes the specified key-value pair.

func WithFields

func WithFields(ctx context.Context, fields map[string]any) context.Context

WithFields returns a new context with a logger that includes all specified key-value pairs.

Types

type ColorHandler

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

ColorHandler wraps slog.TextHandler to add ANSI color codes. It delegates all logic to the underlying TextHandler but intercepts the output to inject color codes for the log level.

func NewColorHandler

func NewColorHandler(w io.Writer, opts *slog.HandlerOptions) *ColorHandler

NewColorHandler creates a handler that adds ANSI color codes to log levels.

func (*ColorHandler) Enabled

func (h *ColorHandler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level.

func (*ColorHandler) Handle

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

Handle formats the record with color-coded levels and writes it.

func (*ColorHandler) WithAttrs

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

WithAttrs returns a new handler with the given attributes added.

func (*ColorHandler) WithGroup

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

WithGroup returns a new handler with the given group name prepended.

type Options

type Options struct {
	// Level sets the minimum log level (Debug, Info, Warn, Error).
	Level slog.Level

	// Format specifies the output format ("text", "json").
	Format string

	// Writer is the destination for log output (defaults to os.Stderr).
	Writer io.Writer

	// ColorEnabled enables ANSI color codes for level and fields (text format only).
	ColorEnabled bool

	// AddSource includes source file and line number in log output.
	AddSource bool

	// IncludeTraceContext adds trace_id and span_id to log records when available.
	IncludeTraceContext bool

	// ExportToOTel enables exporting logs to the OpenTelemetry collector.
	// When enabled, logs are sent both to the writer and to the OTel backend.
	ExportToOTel bool

	// AuditWriter is an optional destination for audit events.
	// When set, log messages starting with "deputy." are written as JSON
	// to this writer in addition to the main output.
	AuditWriter io.Writer
}

Options configures logger behavior including output format and styling.