logging

Documentation

Overview

Package logging provides Spice-native, instance-owned structured logging.

Index

• Constants
• func NewJSONHandler(writer io.Writer, options HandlerOptions) (slog.Handler, error)
• func NewTextHandler(writer io.Writer, options HandlerOptions) (slog.Handler, error)
• type Configuration
• type Controller
  • func (controller *Controller) Reset(scopeID string) error
  • func (controller *Controller) Set(scopeID string, level Level) error
  • func (controller *Controller) Snapshot() LevelSnapshot
• type Correlation
• type ErrorDetails
  • func ClassifyError(err error) ErrorDetails
• type Field
  • func Bool(key string, value bool) Field
  • func Duration(key string, value time.Duration) Field
  • func ErrorFields(err error) []Field
  • func Float64(key string, value float64) Field
  • func Int64(key string, value int64) Field
  • func String(key, value string) Field
  • func Time(key string, value time.Time) Field
  • func Uint64(key string, value uint64) Field
• type Format
• type HandlerOptions
• type Level
  • func ParseLevel(value string) (Level, error)
  • func (level Level) MarshalJSON() ([]byte, error)
  • func (level Level) String() string
• type LevelRule
  • func ParseLevelRules(value string, scopes []Scope) ([]LevelRule, error)
• type LevelSnapshot
• type Logger
  • func New(options Options) (*Logger, error)
  • func (logger *Logger) Controller() *Controller
  • func (logger *Logger) Debug(ctx context.Context, event, message string, fields ...Field) error
  • func (logger *Logger) Emit(ctx context.Context, record Record) error
  • func (logger *Logger) Error(ctx context.Context, event, message string, fields ...Field) error
  • func (logger *Logger) Info(ctx context.Context, event, message string, fields ...Field) error
  • func (logger *Logger) Slog() *slog.Logger
  • func (logger *Logger) Stats() Stats
  • func (logger *Logger) Trace(ctx context.Context, event, message string, fields ...Field) error
  • func (logger *Logger) Warn(ctx context.Context, event, message string, fields ...Field) error
  • func (logger *Logger) WithScope(scope Scope) (*Logger, error)
• type Options
• type Record
• type SafeError
• type Scope
  • func (scope Scope) ID() string
• type ScopeLevel
• type Stats

Constants

const (
	// FormatJSON selects the canonical spice.log/v1 JSON encoding.
	FormatJSON Format = "json"
	// FormatText selects stable developer-oriented key-value text.
	FormatText Format = "text"

	// JSON is the canonical production format.
	JSON = FormatJSON
	// Text is the developer-oriented text format.
	Text = FormatText
)

const (
	// LevelTrace enables the most detailed diagnostic records.
	LevelTrace Level = -8
	// LevelDebug enables developer diagnostic records.
	LevelDebug Level = -4
	// LevelInfo enables ordinary operational records.
	LevelInfo Level = 0
	// LevelWarn enables degraded or rejected operation records.
	LevelWarn Level = 4
	// LevelError enables failed operation records.
	LevelError Level = 8
	// LevelOff disables every record in a configured scope.
	LevelOff Level = 127

	// Trace is the canonical trace severity.
	Trace = LevelTrace
	// Debug is the canonical debug severity.
	Debug = LevelDebug
	// Info is the canonical informational severity.
	Info = LevelInfo
	// Warn is the canonical warning severity.
	Warn = LevelWarn
	// Error is the canonical error severity.
	Error = LevelError
	// Off disables every record in a configured scope.
	Off = LevelOff
)

Functions

func NewJSONHandler

func NewJSONHandler(writer io.Writer, options HandlerOptions) (slog.Handler, error)

NewJSONHandler constructs a canonical spice.log/v1 JSON slog handler.

func NewTextHandler

func NewTextHandler(writer io.Writer, options HandlerOptions) (slog.Handler, error)

NewTextHandler constructs a stable developer-oriented text slog handler.

Types

type Configuration

type Configuration struct {
	Format    Format
	Level     Level
	Levels    []LevelRule
	AddSource bool
}

Configuration is resolved before one logger is constructed.

type Controller

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

Controller owns the mutable level policy for one logger. It is safe for concurrent use and never changes process-global state.

func (*Controller) Reset

func (controller *Controller) Reset(scopeID string) error

Reset removes one runtime override and restores its startup policy.

func (*Controller) Set

func (controller *Controller) Set(scopeID string, level Level) error

Set installs a runtime override for root or one registered exact scope.

func (*Controller) Snapshot

func (controller *Controller) Snapshot() LevelSnapshot

Snapshot returns root followed by exact scopes in lexical ID order.

type Correlation

type Correlation struct {
	TraceID    string
	SpanID     string
	TraceFlags uint8
}

Correlation carries optional W3C-compatible trace identity without owning a tracing SDK or extracting process-global context.

type ErrorDetails

type ErrorDetails struct {
	Kind    string
	Code    string
	Message string
}

ErrorDetails is explicitly reviewed, bounded information safe for logs.

func ClassifyError

func ClassifyError(err error) ErrorDetails

ClassifyError converts an error into safe fixed details.

type Field

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

Field is one typed attribute in a safe Spice record. Its representation is opaque so arbitrary values cannot bypass record validation.

func Bool

func Bool(key string, value bool) Field

Bool constructs one Boolean field.

func Duration

func Duration(key string, value time.Duration) Field

Duration constructs one duration field encoded as nanoseconds.

func ErrorFields

func ErrorFields(err error) []Field

ErrorFields returns bounded fields for automatic observers.

func Float64

func Float64(key string, value float64) Field

Float64 constructs one floating-point field.

func Int64

func Int64(key string, value int64) Field

Int64 constructs one signed integer field.

func String

func String(key, value string) Field

String constructs one bounded string field.

func Time

func Time(key string, value time.Time) Field

Time constructs one timestamp field normalized by the selected handler.

func Uint64

func Uint64(key string, value uint64) Field

Uint64 constructs one unsigned integer field.

type Format

type Format string

Format identifies a built-in caller-owned output format.

type HandlerOptions

type HandlerOptions struct{ AddSource bool }

HandlerOptions configure built-in handlers.

type Level

type Level int8

Level is the severity of one structured record.

func ParseLevel

func ParseLevel(value string) (Level, error)

ParseLevel decodes a case-insensitive canonical level name.

func (Level) MarshalJSON

func (level Level) MarshalJSON() ([]byte, error)

MarshalJSON emits the canonical name used by management responses.

func (Level) String

func (level Level) String() string

String returns the uppercase canonical level name.

type LevelRule

type LevelRule struct {
	Scope Scope
	Level Level
}

LevelRule sets one startup level for an exact non-root scope.

func ParseLevelRules

func ParseLevelRules(value string, scopes []Scope) ([]LevelRule, error)

ParseLevelRules parses comma-separated exact scope=level startup rules.

type LevelSnapshot

type LevelSnapshot struct {
	Scopes []ScopeLevel `json:"scopes"`
}

LevelSnapshot is a deterministic snapshot of root and registered scopes.

type Logger

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

Logger emits through one standard slog.Handler without mutating globals.

func New

func New(options Options) (*Logger, error)

New validates and constructs one application logger.

func (*Logger) Controller

func (logger *Logger) Controller() *Controller

Controller returns this logger's exact-scope level controller.

func (*Logger) Debug

func (logger *Logger) Debug(ctx context.Context, event, message string, fields ...Field) error

Debug emits a debug record in this logger's scope.

func (*Logger) Emit

func (logger *Logger) Emit(ctx context.Context, record Record) error

Emit validates and writes one record. Handler errors are returned and counted; no secondary log is emitted.

func (*Logger) Error

func (logger *Logger) Error(ctx context.Context, event, message string, fields ...Field) error

Error emits an error record in this logger's scope.

func (*Logger) Info

func (logger *Logger) Info(ctx context.Context, event, message string, fields ...Field) error

Info emits an informational record in this logger's scope.

func (*Logger) Slog

func (logger *Logger) Slog() *slog.Logger

Slog returns an instance-owned compatibility adapter. Generic slog values are outside the safe Field contract and remain the caller's responsibility.

func (*Logger) Stats

func (logger *Logger) Stats() Stats

Stats returns a concurrent-safe immutable accounting snapshot.

func (*Logger) Trace

func (logger *Logger) Trace(ctx context.Context, event, message string, fields ...Field) error

Trace emits a trace record in this logger's scope.

func (*Logger) Warn

func (logger *Logger) Warn(ctx context.Context, event, message string, fields ...Field) error

Warn emits a warning record in this logger's scope.

func (*Logger) WithScope

func (logger *Logger) WithScope(scope Scope) (*Logger, error)

WithScope returns an immutable logger for one registered exact scope.

type Options

type Options struct {
	Application   string
	Configuration Configuration
	Writer        io.Writer
	Handler       slog.Handler
	Scopes        []Scope
}

Options construct one application-owned logger. Writer and Handler are mutually exclusive; omitting both creates an explicit discard logger.

type Record

type Record struct {
	Timestamp   time.Time
	Level       Level
	Event       string
	Message     string
	Scope       Scope
	Correlation Correlation
	Fields      []Field
}

Record is one validated Spice-native structured event.

type SafeError

type SafeError interface {
	error
	SafeLogError() ErrorDetails
}

SafeError opts one error into reviewed structured details. Implementations must never return secrets, user content, raw rejected input, or stack traces.

type Scope

type Scope struct {
	Module    string
	Component string
}

Scope is one exact logging ownership boundary. A component always belongs to a module; the zero value is the application root.

func (Scope) ID

func (scope Scope) ID() string

ID returns the canonical exact control identity for this scope.

type ScopeLevel

type ScopeLevel struct {
	Scope           string `json:"scope"`
	ConfiguredLevel Level  `json:"configured_level"`
	EffectiveLevel  Level  `json:"effective_level"`
	Overridden      bool   `json:"overridden"`
}

ScopeLevel is one immutable level-control snapshot item.

type Stats

type Stats struct {
	Attempted uint64 `json:"attempted"`
	Emitted   uint64 `json:"emitted"`
	Filtered  uint64 `json:"filtered"`
	Failed    uint64 `json:"failed"`
}

Stats is an immutable logger accounting snapshot.