Leveled, structured logging to stderr, as logfmt or JSON lines. There is no global logger (Auk has no global mutable state): build a Logger value and pass it around, or keep one in a module-level let. Loggers are values, so with returns a new logger and never changes the old one.
Effects: none (eprint is always allowed). Depends on json (no effects). Lines carry no timestamp, since reading the clock needs uses time; most log collectors add one, or add a field yourself with .with("ts", time.now()).
fn main(): int! uses env {
let lv = log.level(env.get("LOG") else "info")?
let l = log.new(lv).with("svc", "api")
l.info("listening", {"port": Int(8080)}) // level=info msg=listening svc=api port=8080
l.debug("not shown at info")
let j = l.json()
j.warn("slow request", {"ms": Int(950)}) // {"level":"warn","msg":"slow request","svc":"api","ms":950}
0
}API#
enum Level { Debug, Info, Warn, Error }struct Logger { min: Level, json: bool, fields: {str: Value} }new(min: Level): Logger: a logfmt logger that keeps lines atminand above.json(l: Logger): Logger: the same logger, writing one JSON object per line.with<T: Data>(l: Logger, key: str, v: T): Logger: adds a field to every line (anyDatavalue; a struct becomes a nested object). A laterwithof the same key replaces it.debug,info,warn,error(l: Logger, msg: str), and the same with a third argumentfields: {str: Value}for fields on this line only.log(l: Logger, lv: Level, msg: str, fields: {str: Value}): the general form.line(l, lv, msg, fields): str?: the text that would be written, or none when filtered out (pure; for tests or other sinks).enabled(l: Logger, lv: Level): bool: skip building an expensive message.level(s: str): Level!: parsesdebug,info,warn/warningorerror, ignoring case and surrounding spaces.name(lv): stris the reverse.
Each line is level, msg, the logger's fields in the order they were added, then the line's own fields. In logfmt, a string value is written bare unless it is empty or contains a space, =, ", \ or a control char, in which case it is quoted with JSON escapes. Lists and maps are written as compact JSON. Unsafe chars in keys become _.