Skip to main content

Log

Log writes lines of a log to the standard error, each with the time in UTC and its level. It is written in SG in the module std. There is nothing to set up: the first line written makes it ready.

void main() {
var port = 8080
Log.info($"listening on {port}")
Log.debug("not written: Debug is below Info")
Log.warn("disk 91% full")
print("done")
}

It prints done, and on the standard error:

2026-11-19T20:15:03.123Z INFO listening on 8080
2026-11-19T20:15:03.123Z WARN disk 91% full

The time is RFC 3339 with milliseconds, the level is padded to five letters so the messages line up, and there is nothing else on the line: no file, no line number, no fields of its own.

SignatureWhat it does
void Log.trace(read string message)A line at Trace, the most detailed level
void Log.debug(read string message)A line at Debug
void Log.info(read string message)A line at Info
void Log.warn(read string message)A line at Warn
void Log.error(read string message)A line at Error; the program goes on
void Log.setLevel(LogLevel level)From now on, lines of level and above are written; Off writes none
LogLevel Log.level()The level lines are written from
bool Log.isOn(LogLevel level)Whether a line of level would be written

LogLevel is Trace, Debug, Info, Warn, Error or Off, in that order: LogLevel.Warn > LogLevel.Info. Any task may set the level, and every task's next line follows it.

The level​

A program starts at Info, or at the level the variable of the environment SG_LOG names: trace, debug, info, warn, error or off, in any case. Log.setLevel changes it afterwards, so a program with a --verbose flag of its own has the last word. A value of SG_LOG that names no level does not stop the program: one line says so, and Info is used.

$ SG_LOG=debug ./server
$ SG_LOG=verbose ./server
2026-11-19T20:15:03.123Z WARN SG_LOG is "verbose", which is not a level (trace, debug, info, warn, error, off); Info is used

A level that is off​

The compiler writes Log.debug($"...") as if Log.isOn(LogLevel.Debug) { Log.debug($"...") }, so the text of a line that is not written is never built: a level that is off costs a load and a compare. A call inside the text does not run either, as with the macros of Rust's log:

int look(ref int count) {
count += 1
return count
}

void main() {
var count = 0
Log.debug($"found {look(ref count)}")
print($"looked {count} times")
Log.setLevel(LogLevel.Debug)
Log.debug($"found {look(ref count)}")
print($"looked {count} times")
}

It prints:

looked 0 times
looked 1 times

Work done only for the log goes inside Log.isOn:

if Log.isOn(LogLevel.Trace) {
var summary = summarize(read requests)
Log.trace($"requests: {summary}")
}

A message is only written​

The text of a message is never read for anything in it: no ${...} is looked up and no pattern takes arguments, so a text from outside cannot make the log do anything (Log4Shell, CVE-2021-44228, came from a lookup in a message). It takes a finished string; $"..." is put together when the program is compiled, and a value put into it is never read again.

Each line comes from one call. A line break and every other control character in a message is escaped when it is written (\n, \r, \t, the others as \u001b), and so are the characters that cannot be seen or that turn the text around them: the marks of direction, the characters of no width and the byte order mark (‮). A backslash is written \\, so a \n that was in the text is not taken for an escaped line break. A user who sends a line break cannot add a line of their own, and a log shown in a terminal cannot be driven by escape sequences.

void main() {
var user = "bob\n2026-11-19T20:15:03.123Z INFO admin logged in"
Log.warn($"login failed for {user}")
Log.warn("${jndi:ldap://example.com/a}")
print("written")
}

It prints written, and on the standard error:

2026-11-19T20:15:03.123Z WARN login failed for bob\n2026-11-19T20:15:03.123Z INFO admin logged in
2026-11-19T20:15:03.123Z WARN ${jndi:ldap://example.com/a}

Each line is made whole and written at once, so the lines of tasks never mix, with each other or with printError. A line goes out when it is written: nothing waits in a buffer to be lost when the program stops.

Colours​

When the standard error is a terminal, the level is coloured: ERROR red, WARN yellow, INFO green, DEBUG blue and TRACE grey; the message never is. Into a file or a pipe there are no colours, and none when NO_COLOR is set or TERM is dumb. On Windows the console is asked to take the escape sequences, and an old one that refuses them shows no colour.

Not here yet​

Files and their rotation, fields of a structured log (JSON lines), a level for each module, and a way to force colours on. A program that needs them writes its own lines with Stderr or a StreamWriter.