log

Documentation

Overview

Package log provides a leveled logger with emoji-rich console output for the iterion workflow engine.

Index

• func BlockPreview(s string, max int) string
• func Truncate(s string, max int) string
• type Format
• type Level
  • func ParseLevel(s string) (Level, error)
  • func ResolveLevel(explicit string, envVar string) (Level, error)
  • func (l Level) String() string
• type Logger
  • func New(level Level, w io.Writer) *Logger
  • func NewWithFormat(level Level, w io.Writer, format Format) *Logger
  • func Nop() *Logger
  • func (l *Logger) Debug(format string, args ...any)
  • func (l *Logger) Error(format string, args ...any)
  • func (l *Logger) Info(format string, args ...any)
  • func (l *Logger) IsEnabled(level Level) bool
  • func (l *Logger) Level() Level
  • func (l *Logger) LogBlock(level Level, emoji string, header string, body string)
  • func (l *Logger) Logf(level Level, emoji string, format string, args ...any)
  • func (l *Logger) Trace(format string, args ...any)
  • func (l *Logger) Warn(format string, args ...any)
  • func (l *Logger) WithError(err error) *Logger
  • func (l *Logger) WithField(key string, value any) *Logger
  • func (l *Logger) WithFields(fields map[string]any) *Logger
  • func (l *Logger) Writer() io.Writer

Functions

func BlockPreview

func BlockPreview(s string, max int) string

BlockPreview returns s truncated to at most max bytes, preserving newlines. The byte cut is rune-safe (see Truncate). If truncated, a "...[truncated]" marker is appended on a new line.

func Truncate

func Truncate(s string, max int) string

Truncate returns s truncated to at most max bytes with a suffix if it exceeds max. When the byte boundary falls inside a multi-byte UTF-8 sequence (CJK characters, emoji, etc.) the truncation is pulled back to the previous rune start so the returned string stays valid UTF-8 — otherwise json.Marshal escapes the dangling bytes as � and the persisted log field looks garbled downstream. Useful for limiting field sizes in log output and events.

Types

type Format

type Format int

Format selects between the human-readable console format and the structured JSON format used by the cloud-mode server / runner.

const (
	// FormatHuman emits the legacy "HH:MM:SS emoji message" line. This
	// is the default and preserves byte-for-byte compatibility with
	// pre-cloud iterion output.
	FormatHuman Format = iota
	// FormatJSON emits one JSON object per line; see jsonRecord for the
	// schema. Suitable for shipping logs into Loki / ELK / CloudWatch.
	FormatJSON
)

type Level

type Level int

Level represents a logging verbosity level.

const (
	LevelError Level = iota
	LevelWarn
	LevelInfo
	LevelDebug
	LevelTrace
)

func ParseLevel

func ParseLevel(s string) (Level, error)

ParseLevel converts a string to a Level. Case-insensitive. Returns LevelInfo if the string is empty.

func ResolveLevel

func ResolveLevel(explicit string, envVar string) (Level, error)

ResolveLevel resolves the log level from explicit value, env var fallback, and default. The explicit value takes precedence over the env var.

func (Level) String

func (l Level) String() string

String returns the human-readable name of the level.

type Logger

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

Logger is a leveled logger that writes either emoji-rich human output (default) or structured JSON. Loggers may carry a fixed set of fields via WithField/WithFields/WithError; the underlying writer and mutex are shared between forks so concurrent log lines never interleave.

func New

func New(level Level, w io.Writer) *Logger

New creates a new Logger with the given level and writer in the human-readable format. Equivalent to NewWithFormat(level, w, FormatHuman).

func NewWithFormat

func NewWithFormat(level Level, w io.Writer, format Format) *Logger

NewWithFormat creates a new Logger with an explicit format. A nil writer is treated as io.Discard so callers using the "silence all output" idiom (passing nil) don't panic on the first log line.

func Nop

func Nop() *Logger

Nop returns a logger that discards all output (level below error).

func (*Logger) Debug

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

Debug logs at debug level with 🔍 prefix.

func (*Logger) Error

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

Error logs at error level with ❌ prefix.

func (*Logger) Info

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

Info logs at info level with a contextual prefix (caller chooses emoji).

func (*Logger) IsEnabled

func (l *Logger) IsEnabled(level Level) bool

IsEnabled returns true if the given level would produce output.

func (*Logger) Level

func (l *Logger) Level() Level

Level returns the configured log level.

func (*Logger) LogBlock

func (l *Logger) LogBlock(level Level, emoji string, header string, body string)

LogBlock logs a header line followed by a multi-line indented body block. The entire output is written in a single mutex-protected write to prevent interleaving from concurrent goroutines. If body is empty, only the header is printed.

In JSON mode, the body is collapsed into the "body" field of the record so downstream tooling sees a single structured event rather than an indented blob.

func (*Logger) Logf

func (l *Logger) Logf(level Level, emoji string, format string, args ...any)

Logf logs a pre-formatted message at the given level with a custom emoji prefix. This is useful when callers want to choose their own emoji.

func (*Logger) Trace

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

Trace logs at trace level with 🔬 prefix.

func (*Logger) Warn

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

Warn logs at warn level with ⚠️ prefix.

func (*Logger) WithError

func (l *Logger) WithError(err error) *Logger

WithError returns a fork carrying the given error under the "error" field. nil errors are a no-op (the fork has no extra context).

func (*Logger) WithField

func (l *Logger) WithField(key string, value any) *Logger

WithField returns a fork of l carrying the given (key, value) pair in its context. The fork shares the underlying writer and mutex so concurrent writes from parent + child interleave atomically.

func (*Logger) WithFields

func (l *Logger) WithFields(fields map[string]any) *Logger

WithFields returns a fork of l carrying every (key, value) pair from fields. nil and empty maps return a no-op fork (still safe to call on a nil logger).

func (*Logger) Writer

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

Writer returns the underlying io.Writer. Useful for callers that need to compose new loggers that tee output to additional sinks (e.g. a per-run buffer) without losing the original destination.