std/logger is an Elixir-style logger written in Agentica. Import it with import Logger from "std/logger".

The first call of any Logger function attaches a handler named console. It writes text lines to stderr at level info. A program that only logs needs no setup.

Levels #

Logger.debug(message: String, fields: Map[String, String] = {}) -> Void
Logger.info(message: String, fields: Map[String, String] = {}) -> Void
Logger.warning(message: String, fields: Map[String, String] = {}) -> Void
Logger.err(message: String, fields: Map[String, String] = {}) -> Void
Logger.log(level: Logger.Level, message: String, fields: Map[String, String] = {}) -> Void
Logger.level() -> Logger.Level
Logger.set_level(level: Logger.Level) -> Void
Logger.enabled?(level: Logger.Level) -> Bool
  • The levels are the enum Logger.Level: Logger.Level.Debug < Logger.Level.Info < Logger.Level.Warning < Logger.Level.Error.
  • The function for the last level is err, because error is reserved. The output still says error.
  • fields is optional and defaults to {}. So Logger.info("started") and Logger.info("request done", {"path": "/items"}) are both calls.
  • The global level starts at info, and set_level changes it. Every call checks it first, and a call below it makes no event.
  • Each handler has its own level, and gets only the events at or above it.
  • enabled? is true only when the level is at or above the global level and some handler accepts it. Put a costly message inside an if on enabled?.

In the example, the console handler is at info. So enabled? is false for debug until a handler at debug is attached.

import Logger from "std/logger"

def count_lines() -> Int = 3

def main() -> Void
  Logger.set_level(Logger.Level.Debug)
  puts(Logger.enabled?(Logger.Level.Debug))
  _ = Logger.attach("trace", Logger.Level.Debug, &Logger.stderr_text)
  puts(Logger.enabled?(Logger.Level.Debug))
  if Logger.enabled?(Logger.Level.Debug)
    Logger.debug("lines", {"count": count_lines().to_s})
  end

  Logger.set_level(Logger.Level.Info)
  puts(Logger.enabled?(Logger.Level.Debug))
end
Output
false
true
false

Handlers #

Logger.attach(name: String, level: Logger.Level, handler: Fn[Logger.Event, Void]) -> Result[Void]
Logger.detach(name: String) -> Result[Void]
Logger.handlers() -> List[String]

A handler is a function (such as &Logger.stderr_json) or a block. It takes a Logger.Event, with these fields:

  • level: Logger.Level
  • message: String
  • fields: Map[String, String]
  • time_ms: Int: when the event was made
  • task: Int: the task that logged. main is 1

attach with a name in use, and detach with a name not in use, return an error.

  • Handlers run in the order they were attached, synchronously, in the task that logs. So a line is written when the log call returns.
  • An event keeps the handlers it started with. A handler that detaches another does not change the event in progress.
  • A handler stays attached when the task that attached it ends.
  • A handler error is the error of the task that logged.
import Logger from "std/logger"

def main() -> Void
  _ = Logger.detach("console")
  _ = Logger.attach("audit", Logger.Level.Warning) do |event| puts("audit: #{event.message}") end

  Logger.info("not for the audit handler")
  Logger.err("cannot open the cache")
  puts(Logger.attach("audit", Logger.Level.Info, &Logger.stderr_text).message)
  puts(Logger.handlers())
end
Output
audit: cannot open the cache
a handler named "audit" is already attached
["audit"]

Formats #

Logger.stderr_text(event: Logger.Event) -> Void
Logger.stderr_json(event: Logger.Event) -> Void
Logger.format_text(event: Logger.Event) -> String
Logger.format_json(event: Logger.Event) -> String
Logger.time_text(time_ms: Int) -> String

stderr_text and stderr_json are the built-in handlers. Each writes one line with one IO.warn call. format_text and format_json build the line without writing it, for your own handler.

  • Text: TIME LEVEL MESSAGE key=value ..., with the time in UTC and the level in capitals.
  • A message, key or value is written as a JSON string when it is empty, or has =, a quote, a backslash or a control character. A key or value with a space is also written as a JSON string. So a line is always one line, and a value never looks like a field.
  • JSON: one object per line, with the keys time, level (debug, info, warning or error), msg, fields and task. The fields are nested, so a field named level never clashes with a fixed key.
  • time_text turns milliseconds since the Unix epoch into text such as 2026-10-12T10:15:02.345Z. A year outside 0 to 9999 is written with its sign and at least four digits.
import Logger from "std/logger"

def main() -> Void
  event = Logger.Event(
    level: Logger.Level.Info,
    message: "request done",
    fields: {"path": "/items", "status": "200"},
    time_ms: 1760523302345,
    task: 1,
  )

  puts(Logger.format_text(event))
  puts(Logger.format_json(event))
  odd = Logger.Event(level: Logger.Level.Error, message: "a=b", fields: {"note": "two words"}, time_ms: 0, task: 2)
  puts(Logger.format_text(odd))
end
Output
2025-10-15T10:15:02.345Z INFO request done path=/items status=200
{"time":"2025-10-15T10:15:02.345Z","level":"info","msg":"request done","fields":{"path":"/items","status":"200"},"task":1}
1970-01-01T00:00:00.000Z ERROR "a=b" note="two words"

File output and slow handlers #

There is no built-in file handler. A block that appends one line per event does the job. The _ = drops a write error:

import Logger from "std/logger"

def main() -> Void
  _ = Logger.attach("file", Logger.Level.Info) do |event|
    _ = File.append_text("app.log", Logger.format_json(event) + "\n", 1000)
  end

  Logger.info("server started")
end

A slow handler can hand each event to a task over a Channel. The writer is started with Task.spawn_owning, so it owns the channel. The run ends in this order: detach the handler, close the channel, await the writer. Without the await, returning from main ends the run and the queued lines are lost.

import Logger from "std/logger"

def write_events(events: Channel[Logger.Event]) -> Result[Void]
  while true
    case events.recv(1000)
      ok(event) -> try File.append_text("app.log", Logger.format_json(event) + "\n", 1000)
      error(_) -> break if events.closed? and events.empty?
    end
  end

  ok()
end

def main() -> Void
  events: Channel[Logger.Event] = Channel.new(64)
  writer = Task.spawn_owning(&write_events, events)
  _ = Logger.attach("file", Logger.Level.Info) do |event| _ = events.send(event, 1000) end

  Logger.info("server started")
  _ = Logger.detach("file")
  events.close
  done = Task.await(writer)
  if !done.ok?
    IO.warn(done.message)
  end
end

Rules #

  • Logger.Level and Logger.Event are the builtin types LogRegistry.Level and LogRegistry.Event, which std/logger re-exports, so import {Event, Level} from "std/logger" binds them by name. A diagnostic, help and a printed value show Logger.Level and Logger.Event: "#{level}" is Logger.Level.Info, and an event prints as Logger.Event(level: ..., message: ...). They reserve no name: a program may declare its own Event or LogEvent.
  • Handlers and the global level live in the VM, and belong to one run. A child started with Process.spawn has its own. This registry is the language’s only global state; std/logger reaches it through the internal module LogRegistry, which no other module can name (CHECK-UNKNOWN-NAME).
  • Not planned for std/logger: log files and rotation, syslog, sampling, per-module levels, JSON.Value field values, configuration through environment variables, and lazy log arguments (a block given to attach is a handler, not a lazy message). Not planned for tracing: a language-level trace, trace lines on stdout, counters inside the tracer, a flag to turn stack traces off, and a stack of the parent task at spawn time; VM tracing is a developer tool of the VM, not a language feature.
  • There are no flags and no per-task metadata. Pass fields on each call, as the optional second argument.
  • Log calls are normal code, and count against --max-steps.
  • A call below the global level, or one that no handler accepts, costs one function call, one builtin call and one comparison. A call without fields also passes an empty map.