std.logging

std.logging is level gated logging to stderr, added in 0.5.3. Every message carries a level, you set one process-wide threshold, and a message prints only when its level sits at or above that threshold. Logs go to stderr, so a program’s real output on stdout stays clean underneath them.

@import std.logging

Imported names are flat: after @import std.logging you call log_info and the rest with no prefix. See stdlib overview for how imports work in general.

Levels

LogLevel is an enum with four cases, ranked from least to most severe.

enum LogLevel {
    Debug,
    Info,
    Warn,
    Error,
}

The order is Debug < Info < Warn < Error. The threshold starts at Info, so a fresh program drops Debug and prints Info, Warn, and Error.

Functions

func log_set_level(l: LogLevel) -> void
func log_debug(msg: string) -> void
func log_info(msg: string) -> void
func log_warn(msg: string) -> void
func log_error(msg: string) -> void

• log_set_level(l) sets the process-wide threshold. A later log call fires only when its own level is at or above l, and anything below l is dropped. The default is Info.
• log_debug(msg) logs at Debug, tagged [debug].
• log_info(msg) logs at Info, tagged [info].
• log_warn(msg) logs at Warn, tagged [warn].
• log_error(msg) logs at Error, tagged [error].

Each of the four writes its tag and then msg to stderr as one line, and each is a no-op when its own level sits below the current threshold.

logging.dusk

@paradigm procedural

@import std.logging

func main() -> int32 {
    log_info("starting up")            // [info] starting up
    log_debug("skipped by default")    // dropped, Debug is below Info

    log_set_level(LogLevel.Debug)
    log_debug("now the debug line shows")   // [debug] now the debug line shows
    log_warn("running low on memory")       // [warn] running low on memory
    log_error("out of memory")              // [error] out of memory
    return 0
}

The threshold across threads

The threshold lives in the C runtime as one atomic word shared by every thread, so a log_set_level from any thread takes effect everywhere at that thread’s next log call. There is one threshold for the whole process, not one per thread.

Because every message goes to stderr and never stdout, you can turn diagnostics up as loud as you like without disturbing the data a program writes for a pipe or a file to consume. Redirect stderr on its own to capture the log, or send it to /dev/null to silence the log while stdout stays intact.

See also

• std.io: the print builtins and printerr, the stdout and ad hoc stderr surface std.logging sits beside.
• stdlib overview: the full module list and how imports resolve.