packages /

log 0.1.0

Leveled, structured logging to stderr, as logfmt or JSON lines.

files / src/lib.auk 6.5 kB · 177 lines

/// Leveled, structured logging to stderr, as logfmt or JSON lines. No global state: build a
/// `Logger` and pass it (or keep one in a module-level `let`). No effects: `eprint` is always
/// allowed. Lines carry no timestamp; add one with `.with("ts", time.now())` if you need it.

/// How important a line is. A logger drops lines below its minimum level.
pub enum Level { Debug, Info, Warn, Error }

/// A logger: its minimum level, output format, and the fields every line carries.
pub struct Logger { min: Level, json: bool, fields: {str: Value} }

/// A logfmt logger (`level=info msg=started port=8080`) that keeps lines at `min` and above.
pub fn new(min: Level): Logger = Logger { min, json: false, fields: {} }

/// The same logger, writing one JSON object per line instead of logfmt.
pub fn json(l: Logger): Logger = Logger { json: true, ..l }

/// The same logger with a field added to every line (a later `with` of the same key replaces it).
/// Any `Data` value works: `l.with("user", "ann").with("attempt", 3)`.
pub fn with<T: Data>(l: Logger, key: str, v: T): Logger {
  var fields = l.fields
  fields[key] = to_value(v)
  Logger { fields, ..l }
}

/// A level from its name, ignoring case: `debug`, `info`, `warn` (or `warning`), `error`.
/// Handy for `log.level(env.get("LOG") else "info")?`.
pub fn level(s: str): Level! = match s.trim().lower() {
  "debug" => Debug
  "info" => Info
  "warn" => Warn
  "warning" => Warn
  "error" => Error
  _ => fail("unknown log level: {s}")
}

/// The lower-case name of a level.
pub fn name(Debug): str = "debug"
pub fn name(Info): str = "info"
pub fn name(Warn): str = "warn"
pub fn name(Error): str = "error"

fn rank(Debug): int = 0
fn rank(Info): int = 1
fn rank(Warn): int = 2
fn rank(Error): int = 3

/// Would a line at `lv` be written? Use it to skip building expensive messages.
pub fn enabled(l: Logger, lv: Level): bool = rank(lv) >= rank(l.min)

pub fn debug(l: Logger, msg: str) { l.log(Debug, msg, {}) }
pub fn info(l: Logger, msg: str) { l.log(Info, msg, {}) }
pub fn warn(l: Logger, msg: str) { l.log(Warn, msg, {}) }
pub fn error(l: Logger, msg: str) { l.log(Error, msg, {}) }

/// The same, with fields for this line only: `l.info("saved", {"id": Int(7)})`.
pub fn debug(l: Logger, msg: str, fields: {str: Value}) { l.log(Debug, msg, fields) }
pub fn info(l: Logger, msg: str, fields: {str: Value}) { l.log(Info, msg, fields) }
pub fn warn(l: Logger, msg: str, fields: {str: Value}) { l.log(Warn, msg, fields) }
pub fn error(l: Logger, msg: str, fields: {str: Value}) { l.log(Error, msg, fields) }

/// Write one line to stderr if `lv` is enabled.
pub fn log(l: Logger, lv: Level, msg: str, fields: {str: Value}) {
  let text = l.line(lv, msg, fields) else return
  eprint(text)
}

/// The text `log` would write (without the line break), or none when `lv` is filtered out.
/// Order: `level`, `msg`, the logger's fields, then this line's fields.
pub fn line(l: Logger, lv: Level, msg: str, fields: {str: Value}): str? {
  if !l.enabled(lv) { return none }
  var all: [(str, Value)] = [("level", Str(name(lv))), ("msg", Str(msg))]
  for k, v in l.fields { all.push((k, v)) }
  for k, v in fields { all.push((k, v)) }
  if l.json {
    let parts = all.map((k, v) => json.str(Str(k)) + ":" + json.str(v))
    some("{{" + parts.join(",") + "}}")
  } else {
    some(all.map((k, v) => "{fmt_key(k)}={logfmt(v)}").join(" "))
  }
}

// ---- logfmt ----

// A logfmt value: bare when it's safe, quoted (JSON-style escapes) otherwise; lists and maps
// are written as compact JSON.
fn logfmt(Str(s)): str = quote_if_needed(s)
fn logfmt(Null): str = "null"
fn logfmt(Bool(b)): str = "{b}"
fn logfmt(Int(n)): str = "{n}"
fn logfmt(Float(f)): str = json.str(Float(f))
fn logfmt(v: Value): str = quote_if_needed(json.str(v))

fn quote_if_needed(s: str): str = if s == "" ||
  s.chars().any(c => c == ' ' || c == '=' || c == '"' || c == '\\' || int(c) < 0x20) {
  json.str(Str(s))
} else {
  s
}

// Keys can't be quoted in logfmt, so unsafe chars become `_`.
fn fmt_key(k: str): str {
  let cs = k.chars().map(
    c => if c == ' ' || c == '=' || c == '"' || int(c) < 0x20 { '_' } else { c },
  )
  if cs.len() == 0 { "_" } else { str(cs) }
}

// ---- tests ----

test "levels filter" {
  let l = new(Warn)
  assert !l.enabled(Debug) && !l.enabled(Info)
  assert l.enabled(Warn) && l.enabled(Error)
  assert l.line(Info, "hi", {}) is none
  assert l.line(Error, "boom", {}) is some("level=error msg=boom")
  assert new(Debug).line(Debug, "x", {}) is some("level=debug msg=x")
}

test "parse level names" {
  assert level("debug")? == Debug
  assert level("INFO")? == Info
  assert level(" Warning ")? == Warn
  assert level("warn")? == Warn
  assert level("error")? == Error
  assert level("loud") is err(_)
  assert [Debug, Info, Warn, Error].map(v => name(v)) == ["debug", "info", "warn", "error"]
}

test "logfmt fields and quoting" {
  let l = new(Info).with("svc", "api").with("port", 8080)
  assert l.line(Info, "started", {}) is some("level=info msg=started svc=api port=8080")
  assert l.line(Info, "request done", {"path": Str("/a b"), "ok": Bool(true), "ms": Float(1.5)}) ==
    some("level=info msg=\"request done\" svc=api port=8080 path=\"/a b\" ok=true ms=1.5")
  let q = new(Debug)
  assert q.line(Info, "", {
    "e": Str("x=\"1\"\n"),
  }) is some("level=info msg=\"\" e=\"x=\\\"1\\\"\\n\"")
  assert q.line(Info, "m", {
    "n": Null,
    "xs": List([Int(1), Int(2)]),
  }) is some("level=info msg=m n=null xs=[1,2]")
  assert q.line(Info, "m", {
    "m": Map({"a": Str("b c")}),
  }) is some("level=info msg=m m=\"{{\\\"a\\\":\\\"b c\\\"}}\"")
  assert q.line(Info, "m", {"bad key=": Int(1)}) is some("level=info msg=m bad_key_=1")
}

test "with replaces a key and keeps order" {
  let l = new(Info).with("a", 1).with("b", 2).with("a", "z")
  assert l.line(Info, "m", {}) is some("level=info msg=m a=z b=2")
  let base = new(Info)
  let _ = base.with("k", 1)
  assert base.fields.len() == 0  // loggers are values: `with` returns a new one
}

struct Req { id: int, path: str }

test "json lines" {
  let l = new(Debug).json().with("svc", "api")
  assert l.line(Warn, "slow \"q\"", {"ms": Int(250)}) ==
    some(r"""{"level":"warn","msg":"slow \"q\"","svc":"api","ms":250}""")
  let r = l.with("req", Req { id: 7, path: "/x" })
  assert r.line(
    Info,
    "ok",
    {},
  ) is some(r"""{"level":"info","msg":"ok","svc":"api","req":{"id":7,"path":"/x"}}""")
  assert new(Error).json().line(Info, "x", {}) is none
}

test "writing does not fail" {
  let l = new(Error)
  l.debug("dropped")
  l.info("dropped", {"k": Int(1)})
  l.warn("dropped")
  l.error("written to stderr by the test", {"k": Int(1)})
}