Skip to content

std::log

Structured logging. A Logger writes each record, a level, a message and a list of fields, as one line to a Writer: Logger.text as key=value pairs, Logger.json as one JSON object. log.info(logger, "order placed", [log.int("order", 42)]) writes time=… level=INFO msg="order placed" order=42.

A program keeps its logger in an app field and logs through it (log.info(App.logger, …)), so a test or one part of the program can replace it with with App.logger = …. A library takes a Logger parameter. std::log::testing records what a body logs as values.

Import with import std::log.

A logger has a minimum level, Info unless set, and drops records below it: Logger.text(min: Level.Debug) writes everything. The levels, from lowest, are Debug, Info, Warn and Error.

A field is a key and a typed value: log.string, log.int, log.float, log.bool, and log.any for any Display value, which is written as its text. Logger.with_fields makes a logger that adds fields to every record it writes, as slog’s With does: request_log = Logger.with_fields(App.logger, [log.string("path", path)]).

Each record is written with one write, so lines from tasks sharing a logger never interleave. Its time is Instant.now(), so under clock Clock.Virtual a test’s records carry stable times. A failed write is dropped: logging never fails the program.

enum Level
    Debug
    Info
    Warn
    Error
end

How severe a record is. A logger drops records below its minimum.

fn rank(level: Level) -> Int

type function on Level

The level’s position from lowest, for comparing two levels.

assert Level.rank(Level.Debug) < Level.rank(Level.Error)
fn is_at_least(level: Level, min: Level) -> Bool

type function on Level

Whether level is min or above it.

assert Level.is_at_least(Level.Warn, Level.Info)
assert not Level.is_at_least(Level.Debug, Level.Info)

impl Display for Level

fn to_string(level: Level) -> String

impl Display.to_string

assert "${Level.Warn}" == "WARN"

impl Debug for Level

fn inspect(value: Level) -> String

impl Debug.inspect

impl Equatable for Level

fn equal(a: Level, b: Level) -> Bool

impl Equatable.equal

enum Value
    Text String
    Int Int
    Float Float
    Bool Bool
end

A field’s value, which the JSON logger writes as its JSON type.

impl Debug for Value

fn inspect(value: Value) -> String

impl Debug.inspect

impl Equatable for Value

fn equal(a: Value, b: Value) -> Bool

impl Equatable.equal

struct Field
    key: String
    value: Value
end

One key and its value on a record.

impl Debug for Field

fn inspect(value: Field) -> String

impl Debug.inspect

impl Equatable for Field

fn equal(a: Field, b: Field) -> Bool

impl Equatable.equal

fn string(key: String, value: String) -> Field

A text field.

assert string("user", "Ada") == Field{key: "user", value: .Text("Ada")}
fn int(key: String, value: Int) -> Field

An integer field.

fn float(key: String, value: Float) -> Field

A floating-point field.

fn bool(key: String, value: Bool) -> Field

A boolean field.

fn any(key: String, value: Display) -> Field

A field holding any Display value as its text.

assert any("retries", 3) == string("retries", "3")
struct Logger

opaque — construction surface is private to its defining module

Where records go and which of them are written: build one with Logger.text, Logger.json or Logger.discard.

fn text(writer: Writer = io.stderr, min: Level = Level.Info) -> Logger

type function on Logger

A logger that writes each record as key=value pairs on one line, as slog’s text handler does: time=… level=INFO msg="order placed" order=42. A value with a space, =, " or a control character, or an empty one, is quoted.

import std::io.Writer

(_, out) = Writer.collect(fn w -> info(Logger.text(w), "hi", [int("n", 2)]))
line = Bytes.to_string(out)!
assert String.ends_with(line, " level=INFO msg=hi n=2\n")
fn json(writer: Writer = io.stderr, min: Level = Level.Info) -> Logger

type function on Logger

A logger that writes each record as one JSON object on one line, as slog’s JSON handler does: {"time":…,"level":"INFO","msg":"order placed","order":42}, its fields after msg in order.

import std::io.Writer

(_, out) = Writer.collect(fn w -> warn(Logger.json(w), "slow", [bool("cached", False)]))
line = Bytes.to_string(out)!
assert String.ends_with(line, "\"level\":\"WARN\",\"msg\":\"slow\",\"cached\":false}\n")
fn discard() -> Logger

type function on Logger

A logger that writes nothing.

fn records(writer: Writer, min: Level) -> Logger

type function on Logger

The logger for std::log::testing’s recorder: one JSON array per record. Not for programs; std::log::testing.run builds it.

fn with_fields(logger: Logger, fields: List<Field>) -> Logger

type function on Logger

The same logger, adding fields to every record it writes, after the fields it already adds and before the record’s own.

fn with_min(logger: Logger, min: Level) -> Logger

type function on Logger

The same logger with minimum level min.

fn min(logger: Logger) -> Level

type function on Logger

The logger’s minimum level.

fn is_enabled(logger: Logger, level: Level) -> Bool

type function on Logger

Whether the logger writes a record at level, for skipping work that only builds fields for a record it would drop.

assert not Logger.is_enabled(Logger.text(), Level.Debug)

impl Debug for Logger

fn inspect(value: Logger) -> String

impl Debug.inspect

fn log(logger: Logger, level: Level, message: String, fields: List<Field> = []) -> Unit

Writes a record at level, when the logger’s minimum lets it through.

fn debug(logger: Logger, message: String, fields: List<Field> = []) -> Unit

Writes a Debug record.

fn info(logger: Logger, message: String, fields: List<Field> = []) -> Unit

Writes an Info record.

fn warn(logger: Logger, message: String, fields: List<Field> = []) -> Unit

Writes a Warn record.

fn error(logger: Logger, message: String, fields: List<Field> = []) -> Unit

Writes an Error record.