tracing

Structured logging and span-based distributed tracing with pluggable sinks.

Import

import tracing

Log levels

tracing.set_level(level: str)

Set the minimum level. Levels in order: "trace", "debug", "info", "warn", "error". Messages below the level are dropped.

tracing.get_level() -> str

Return the current minimum level string.

Shortcut emitters

tracing.trace(msg, attrs?), tracing.debug(msg, attrs?), tracing.info(msg, attrs?), tracing.warn(msg, attrs?), tracing.error(msg, attrs?) - emit a structured event at the named level. The optional attrs map is merged into the record.

tracing.event(level: str, msg: str, attrs?: map)

Emit a single event at an arbitrary level.

Sinks

tracing.add_sink(fn: (record: map) -> void)

Register a sink function called for every record that passes the level filter. Records carry name, level, ts (epoch nanoseconds), and kind ("event" or "span").

tracing.remove_sinks()

Clear all registered sinks.

tracing.console_sink(record: map)

Built-in sink that writes colorized text to stderr. Pass to add_sink.

tracing.json_sink(record: map)

Built-in sink that writes one JSON line per record to stderr. Use tracing.json_sink_path(path) to redirect to a file.

tracing.json_sink_path(path?: str)

Set the output file for json_sink. Omit path to reset to stderr.

Spans

tracing.start_span(name: str, attrs?: map) -> handle

Open a span and return a handle. The span is open until end_span is called.

tracing.end_span(handle: map, attrs?: map)

Close a span. Fires all sinks with a span record including duration_ns.

tracing.with_span(name: str, fn: () -> any) -> any

Run a function inside a span. end_span is called even if the function throws. Returns the function's result.

Examples

import tracing

tracing.add_sink(tracing.console_sink)
tracing.set_level("debug")

tracing.info("server started", #{"port": 8080})
tracing.warn("high memory usage", #{"mb": 512})

let result = tracing.with_span("db.query", fn() {
    -- simulate work
    tracing.debug("running query")
    return 42
})
println(result)  -- 42