Skip to content

stdlib.log

Structured Logging

Generated from v0.60.1. 5 source files, 73 documented symbols.

color.xi

fn log_color(level: Int) -> Str

The ANSI color sequence for a level (see header for the mapping). Unknown levels return the reset sequence. Complexity: O(1).

fn log_color_reset() -> Str

The ANSI reset sequence. Complexity: O(1).

fn log_color_enabled() -> Bool

Whether colored output is enabled. Complexity: O(1).

fn log_set_color_enabled(on: Bool)

Enable or disable colored output. Complexity: O(1).

fn log_colorize(level: Int, msg: Str) -> Str

Wrap msg in its level color when colored output is enabled; otherwise return msg unchanged. Complexity: O(len(msg)).

fn log_color_by_level(level: Int) -> Int

The numeric ANSI color code assigned to a level (31 for ERROR, 32 for INFO, ...). Returns 0 for unknown levels. Complexity: O(1).

fn log_strip_color(s: Str) -> Str

Remove ANSI color (CSI) sequences from s. Handles sequences of the form ESC [ params letter, including ESC [ m. Complexity: O(len(s)).

fn log_has_color(s: Str) -> Bool

Whether s contains an ANSI color (CSI) sequence (ESC [). Complexity: O(len(s)).

json.xi

type JsonLogEntry

A parsed structured log record: ISO timestamp, level, message, extra key/value fields and the originating thread id.

Field Type
timestamp Str
level Int
message Str
fields Vec[(Str, Str)]
thread_id Int

Derives: Clone

fn log_json_entry(level: Int, msg: Str) -> Str

Build a JSON log line for a level and message, with the current timestamp and thread id. Complexity: O(len(msg)).

fn log_json_fields(fields: &Vec[(Str, Str)]) -> Str

Render extra key/value fields as a JSON object: {"k1":"v1","k2":"v2"}. Empty input renders {}. Complexity: O(sum of field lengths).

fn log_json_timestamp() -> Str

The current time as an ISO 8601 string (via xiom.time.iso8601_now). Complexity: O(1).

fn log_json_parse(line: Str) -> Result[JsonLogEntry, Str]

Parse a JSON log line into an entry. Returns Err when the line is malformed (missing the level, message or timestamp keys). Complexity: O(len(line)).

fn log_json_format(entry: JsonLogEntry) -> Str

Re-serialize a log entry to a JSON line. Complexity: O(len(message) + fields).

fn log_json_thread_id() -> Int

The current thread id for logging. This build is single-threaded, so the value is always 1. Complexity: O(1).

levels.xi

fn log_level_trace() -> Int

The trace level constant (0).

fn log_level_debug() -> Int

The debug level constant (1).

fn log_level_info() -> Int

The info level constant (2).

fn log_level_warn() -> Int

The warn level constant (3).

fn log_level_error() -> Int

The error level constant (4).

fn log_level_fatal() -> Int

The fatal level constant (5).

fn log_level_name(level: Int) -> Str

The canonical name of a level: TRACE, DEBUG, INFO, WARN, ERROR or FATAL. Unknown levels map to "UNKNOWN". Complexity: O(1).

fn log_level_from_name(s: Str) -> Option[Int]

The level for a name, if known. Matching is case-insensitive. Complexity: O(1).

fn log_level_threshold() -> Int

The current minimum level that is logged. Complexity: O(1).

fn log_set_level(level: Int)

Set the minimum level that is logged. Complexity: O(1).

fn log_enabled(level: Int) -> Bool

Whether a level passes the threshold (level >= threshold). Complexity: O(1).

fn log_level_all() -> Vec[Int]

All level constants in severity order: [TRACE, DEBUG, INFO, WARN, ERROR, FATAL]. Complexity: O(1).

log.xi

enum LogLevel

Severity levels, from most to least verbose.

  • Trace
  • Debug
  • Info
  • Warn
  • Error
  • Fatal

type LogEntry

One log record (level, message, timestamp, fields).

Field Type
level LogLevel
message Str
file Str
line Int
timestamp Int
data Map[Str, Str]

Derives: Clone

fn trace(msg: Str)

Core logging

  • Precondition: msg.len() >= 0

fn debug(msg: Str)

Log at debug level.

  • Precondition: msg.len() >= 0

fn info(msg: Str)

Log at info level.

  • Precondition: msg.len() > 0

fn warn(msg: Str)

Log at warn level.

  • Precondition: msg.len() > 0

fn error(msg: Str)

Log at error level.

  • Precondition: msg.len() > 0

fn fatal(msg: Str)

Log at fatal level.

  • Precondition: msg.len() >= 0

fn trace_with(msg: Str, data: Map[Str, Str])

Structured logging (key=value pairs)

  • Precondition: msg.len() >= 0

fn debug_with(msg: Str, data: Map[Str, Str])

Log at debug level with structured fields.

  • Precondition: msg.len() >= 0

fn info_with(msg: Str, data: Map[Str, Str])

Log at info level with structured fields.

  • Precondition: msg.len() > 0

fn warn_with(msg: Str, data: Map[Str, Str])

Log at warn level with structured fields.

  • Precondition: msg.len() > 0

fn error_with(msg: Str, data: Map[Str, Str])

Log at error level with structured fields.

  • Precondition: msg.len() > 0

fn set_level(level: LogLevel)

Configuration

fn get_level() -> LogLevel

Current minimum level that is emitted.

fn set_output(file: Str) -> Result[Unit, Str]

Redirect log output to a file; Err when it cannot be opened.

  • Precondition: file.len() > 0

fn set_output_json(enabled: Bool)

Enable/disable JSON-lines output.

fn set_output_color(enabled: Bool)

Enable/disable ANSI color output.

fn entries_since(instant: Instant) -> Vec[LogEntry]

Query

  • Postcondition: result.len() >= 0

fn clear_log()

Clear any file output and revert to the default sink.

fn log_debug_msg(msg: Str)

Logs a debug-level message. Alias for log.debug for discoverability. Complexity: O(1) if level is filtered, O(1) otherwise.

fn log_info_msg(msg: Str)

Logs an info-level message. Alias for log.info. Complexity: O(1).

fn log_warn_msg(msg: Str)

Logs a warning-level message. Alias for log.warn. Complexity: O(1).

fn log_error_msg(msg: Str)

Logs an error-level message. Alias for log.error. Complexity: O(1).

fn log_with_fields(level: LogLevel, msg: Str, fields: Map[Str, Str]) -> LogEntry

Creates and writes a log entry with the given level, message, and key-value fields. Returns the created LogEntry. Complexity: O(1).

fn log_set_min_level(level: LogLevel)

Sets the minimum log level. Messages below this level are filtered out. Alias for set_level. Complexity: O(1). Thread-safe: modifies global state.

fn log_enable_json(enable: Bool)

Enables or disables JSON output format for log entries. Alias for set_output_json. Complexity: O(1). Thread-safe: modifies global state.

fn log_clear_entries()

Clears all buffered log entries. Alias for clear_log. Complexity: O(1). Thread-safe: modifies global state.

fn log_entry_count() -> Int

Returns the number of buffered log entries. Complexity: O(1). Thread-safe: reads global state.

fn log_last_entry() -> Option[LogEntry]

Returns the most recent log entry, or None if the buffer is empty. Complexity: O(1). Thread-safe: reads global state.

fn log_entries_as_text() -> Str

Returns all buffered entries as a newline-separated text string. Complexity: O(n).

fn log_entries_as_json() -> Str

Returns all buffered entries as a JSON array string. Complexity: O(n).

fn log_flush()

Flushes log output. No-op in this implementation (output is synchronous). Complexity: O(1).

sinks.xi

type Sink

A log output destination wrapping a file or stream target.

Field Type
id Int
target Int
path Str
bytes Int

Derives: Clone

type SinkList

Registry of registered sinks, stored as parallel primitive vectors. Public so the compiler can allocate the module-level instance.

Field Type
ids Vec[Int]
targets Vec[Int]
paths Vec[Str]
fn log_sink_new(target: Int) -> Sink

Wrap a raw fd as a log sink. The sink is NOT auto-registered; call log_add_sink to register it. Complexity: O(1).

fn log_sink_file(path: Str) -> Result[Sink, Str]

Open a file sink for appending. Returns Err when the file cannot be opened for append. Complexity: O(1).

fn log_sink_stdout() -> Sink

A sink that writes to stdout. Complexity: O(1).

fn log_sink_stderr() -> Sink

A sink that writes to stderr. Complexity: O(1).

fn log_sink_null() -> Sink

A sink that discards output. Complexity: O(1).

fn log_add_sink(s: Sink)

Register a sink for future log lines. Duplicate ids are ignored. Complexity: O(registered sinks).

fn log_remove_sink(s: Sink)

Unregister a sink (matched by id). Complexity: O(registered sinks).

fn log_sinks() -> Vec[Sink]

The currently registered sinks. Complexity: O(registered sinks).

fn log_flush_all()

Flush every registered sink. No-op in this build (output is synchronous). Complexity: O(1).

fn log_sink_rotate(s: Sink, max_bytes: Int)

Rotate a file sink once it exceeds max_bytes. This build performs no byte accounting, so the sink's byte counter is never advanced and rotation is a no-op (documented). Complexity: O(1).

fn log_sink_close(s: Sink)

Close a sink and release its resources: unregisters it from the registry. File handles in this build are per-write and need no explicit release. Complexity: O(registered sinks).