Skip to content

stdlib.log

Structured Logging

Generated from v0.65.7. 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).

  • Postcondition: result.len() >= 4
fn log_color_reset() -> Str

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

  • Postcondition: result.len() == 4
fn log_color_enabled() -> Bool

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

  • Postcondition: result == color_enabled
fn log_set_color_enabled(on: Bool)

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

  • Postcondition: color_enabled == on
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)).

  • Postcondition: result.len() >= msg.len()
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).

  • Postcondition: result >= 31 && result <= 90
  • Postcondition: (level <= 0) => (result == 90)
  • Postcondition: (level >= 5) => (result == 35)
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)).

  • Postcondition: result.len() <= s.len()
fn log_has_color(s: Str) -> Bool

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

  • Postcondition: (s.len() < 2) => (result == false)
  • Postcondition: result => (s.len() >= 2)

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)).

  • Postcondition: result.len() >= msg.len() + 40
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).

  • Postcondition: (fields.len() == 0) => (result == "{}")
  • Postcondition: result.len() >= 2
fn log_json_timestamp() -> Str

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

  • Postcondition: result.len() > 0
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)).

  • Postcondition: result is Ok(_) => result.value.level >= 0 && result.value.level <= 5
fn log_json_format(entry: JsonLogEntry) -> Str

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

  • Postcondition: result.len() >= entry.message.len() + 40
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).

  • Postcondition: result == 1

levels.xi

fn log_level_trace() -> Int

The trace level constant (0).

  • Postcondition: result == 0
fn log_level_debug() -> Int

The debug level constant (1).

  • Postcondition: result == 1
fn log_level_info() -> Int

The info level constant (2).

  • Postcondition: result == 2
fn log_level_warn() -> Int

The warn level constant (3).

  • Postcondition: result == 3
fn log_level_error() -> Int

The error level constant (4).

  • Postcondition: result == 4
fn log_level_fatal() -> Int

The fatal level constant (5).

  • Postcondition: result == 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).

  • Postcondition: result.len() >= 4
  • Postcondition: (level <= 0) => (result == "TRACE")
  • Postcondition: (level >= 5) => (result == "FATAL")
fn log_level_from_name(s: Str) -> Option[Int]

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

  • Postcondition: (s.len() == 0) => (result.is_none)
  • Postcondition: result.is_some => (s.len() >= 4)
fn log_level_threshold() -> Int

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

  • Postcondition: result == threshold
fn log_set_level(level: Int)

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

  • Postcondition: threshold == level
fn log_enabled(level: Int) -> Bool

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

  • Postcondition: result == (level >= threshold)
fn log_level_all() -> Vec[Int]

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

  • Postcondition: result.len() == 6

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

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() >= 0

fn debug(msg: Str)

Log at debug level.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() >= 0

fn info(msg: Str)

Log at info level.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() > 0

fn warn(msg: Str)

Log at warn level.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() > 0

fn error(msg: Str)

Log at error level.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() > 0

fn fatal(msg: Str)

Log at fatal level.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() >= 0

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

Structured logging (key=value pairs)

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() >= 0

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

Log at debug level with structured fields.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() >= 0

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

Log at info level with structured fields.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() > 0

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

Log at warn level with structured fields.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() > 0

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

Log at error level with structured fields.

  • Postcondition: entries.len() >= entries.len()@pre
  • Precondition: msg.len() > 0

fn set_level(level: LogLevel)

Configuration

  • Postcondition: current_level == level

fn get_level() -> LogLevel

Current minimum level that is emitted.

  • Postcondition: result == current_level

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.

  • Postcondition: json_mode == enabled

fn set_output_color(enabled: Bool)

Enable/disable ANSI color output.

  • Postcondition: color_mode == enabled

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.

  • Postcondition: entries.len() == 0

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.

  • Postcondition: entries.len() >= entries.len()@pre

fn log_info_msg(msg: Str)

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

  • Postcondition: entries.len() >= entries.len()@pre

fn log_warn_msg(msg: Str)

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

  • Postcondition: entries.len() >= entries.len()@pre

fn log_error_msg(msg: Str)

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

  • Postcondition: entries.len() >= entries.len()@pre

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).

  • Postcondition: result.message == msg
  • Postcondition: result.file.len() == 0
  • Postcondition: result.line == 0

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.

  • Postcondition: current_level == level

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.

  • Postcondition: json_mode == enable

fn log_clear_entries()

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

  • Postcondition: entries.len() == 0

fn log_entry_count() -> Int

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

  • Postcondition: result == entries.len()

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.

  • Postcondition: (entries.len() == 0) => (result.is_none)
  • Postcondition: (entries.len() > 0) => (result.is_some)

fn log_entries_as_text() -> Str

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

  • Postcondition: (entries.len() == 0) => (result.len() == 0)
  • Postcondition: result.len() >= entries.len()

fn log_entries_as_json() -> Str

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

  • Postcondition: (entries.len() == 0) => (result == "[]")
  • Postcondition: result.len() >= 2

fn log_flush()

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

  • Precondition: true

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).

  • Postcondition: result.target == target
  • Postcondition: result.path.len() == 0
  • Postcondition: result.bytes == 0
  • Postcondition: result.id >= 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).

  • Postcondition: result is Ok(_) => result.value.target == 3
  • Postcondition: result is Ok(_) => result.value.path.len() == path.len()
  • Postcondition: result is Ok(_) => result.value.bytes == 0
fn log_sink_stdout() -> Sink

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

  • Postcondition: result.target == 1
  • Postcondition: result.path.len() == 0
  • Postcondition: result.bytes == 0
  • Postcondition: result.id >= 1
fn log_sink_stderr() -> Sink

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

  • Postcondition: result.target == 2
  • Postcondition: result.path.len() == 0
  • Postcondition: result.bytes == 0
  • Postcondition: result.id >= 1
fn log_sink_null() -> Sink

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

  • Postcondition: result.target == 0
  • Postcondition: result.path.len() == 0
  • Postcondition: result.bytes == 0
  • Postcondition: result.id >= 1
fn log_add_sink(s: Sink)

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

  • Postcondition: sink_list.ids.len() == sink_list.targets.len() && sink_list.ids.len() == sink_list.paths.len()
fn log_remove_sink(s: Sink)

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

  • Postcondition: sink_list.ids.len() == sink_list.targets.len() && sink_list.ids.len() == sink_list.paths.len()
fn log_sinks() -> Vec[Sink]

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

  • Postcondition: result.len() == sink_list.ids.len()
fn log_flush_all()

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

  • Precondition: true
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).

  • Postcondition: s.bytes == s.bytes@pre
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).

  • Postcondition: sink_list.ids.len() <= sink_list.ids.len()@pre