a/docs/log.md

log

The log global is for diagnostic output that is separate from a script's results. Where print writes to standard output, log emits level-tagged messages whose visibility is controlled at runtime by an environment variable — so the same script can run quietly in production and verbosely while you debug, with no code change. It is always available as the global log.

log.info("starting run", os.time())
log.warn("retrying after error")
log.error("giving up")

Levels

There is one function per severity level:

Function	Level	Use for
log.trace	TRACE	Very fine-grained, step-by-step detail.
log.debug	DEBUG	Developer diagnostics.
log.info	INFO	Normal high-level progress.
log.warn	WARN	Something unexpected but recoverable.
log.error	ERROR	A failure worth reporting.

log.warning is an alias for log.warn.

Each takes any number of arguments, converts each with tostring, and joins them with a tab, just like print:

log.info("user", userId, "logged in")   --> user    42    logged in

To log a table's structure, render it first with utils.dump:

log.debug("request opts:", utils.dump(opts))

Controlling what is shown

Log output goes to standard error, and which levels are shown is set by the RUST_LOG environment variable. By default only WARN and ERROR appear:

a script.lua                 # default: warnings and errors only
RUST_LOG=info a script.lua   # info and above
RUST_LOG=debug a script.lua  # debug and above
RUST_LOG=trace a script.lua  # everything

A level shows itself and everything more severe — RUST_LOG=info includes info, warn, and error but not debug or trace. Messages below the active level are discarded cheaply, so leaving log.debug calls in place costs almost nothing when they are not enabled.

log vs. print

	print	log
Stream	stdout	stderr
Always shown?	yes	only at/above the active level
Tagged with level?	no	yes

Use print for a script's actual output — the thing a caller pipes or captures. Use log for the running commentary about how it is going, which you want to turn up or down without editing the script.

local rows = con:query("SELECT * FROM users")
log.info("fetched", #rows, "rows")    -- diagnostic; hidden unless RUST_LOG=info
for _, r in ipairs(rows) do
    print(r.name)                      -- the actual result
end

Notes

• Always loaded. No require; log is a global in every script.
• Quiet by default. With no RUST_LOG set, only warn/error are emitted, so info/debug/trace are silent until you opt in.
• Arguments are stringified like print. Multiple arguments are joined with tabs; tables print as their address, so use utils.dump for contents.