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.
Exports
Section titled “Exports”Levels
Section titled “Levels”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.
Fields
Section titled “Fields”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
Section titled “enum Level”enum Level Debug Info Warn Error end
How severe a record is. A logger drops records below its minimum.
Level.rank
Section titled “Level.rank”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)
Level.is_at_least
Section titled “Level.is_at_least”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)
Level.to_string
Section titled “Level.to_string”impl Display for Level
fn to_string(level: Level) -> String
impl Display.to_string
assert "${Level.Warn}" == "WARN"
Level.inspect
Section titled “Level.inspect”impl Debug for Level
fn inspect(value: Level) -> String
impl Debug.inspect
Level.equal
Section titled “Level.equal”impl Equatable for Level
fn equal(a: Level, b: Level) -> Bool
impl Equatable.equal
enum Value
Section titled “enum Value”enum Value Text String Int Int Float Float Bool Bool end
A field’s value, which the JSON logger writes as its JSON type.
Value.inspect
Section titled “Value.inspect”impl Debug for Value
fn inspect(value: Value) -> String
impl Debug.inspect
Value.equal
Section titled “Value.equal”impl Equatable for Value
fn equal(a: Value, b: Value) -> Bool
impl Equatable.equal
struct Field
Section titled “struct Field”struct Field key: String value: Value end
One key and its value on a record.
Field.inspect
Section titled “Field.inspect”impl Debug for Field
fn inspect(value: Field) -> String
impl Debug.inspect
Field.equal
Section titled “Field.equal”impl Equatable for Field
fn equal(a: Field, b: Field) -> Bool
impl Equatable.equal
log.string
Section titled “log.string”fn string(key: String, value: String) -> Field
A text field.
assert string("user", "Ada") == Field{key: "user", value: .Text("Ada")}
log.int
Section titled “log.int”fn int(key: String, value: Int) -> Field
An integer field.
log.float
Section titled “log.float”fn float(key: String, value: Float) -> Field
A floating-point field.
log.bool
Section titled “log.bool”fn bool(key: String, value: Bool) -> Field
A boolean field.
log.any
Section titled “log.any”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
Section titled “struct Logger”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.
Logger.text
Section titled “Logger.text”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")
Logger.json
Section titled “Logger.json”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")
Logger.discard
Section titled “Logger.discard”fn discard() -> Logger
type function on Logger
A logger that writes nothing.
Logger.records
Section titled “Logger.records”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.
Logger.with_fields
Section titled “Logger.with_fields”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.
Logger.with_min
Section titled “Logger.with_min”fn with_min(logger: Logger, min: Level) -> Logger
type function on Logger
The same logger with minimum level min.
Logger.min
Section titled “Logger.min”fn min(logger: Logger) -> Level
type function on Logger
The logger’s minimum level.
Logger.is_enabled
Section titled “Logger.is_enabled”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)
Logger.inspect
Section titled “Logger.inspect”impl Debug for Logger
fn inspect(value: Logger) -> String
impl Debug.inspect
log.log
Section titled “log.log”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.
log.debug
Section titled “log.debug”fn debug(logger: Logger, message: String, fields: List<Field> = []) -> Unit
Writes a Debug record.
log.info
Section titled “log.info”fn info(logger: Logger, message: String, fields: List<Field> = []) -> Unit
Writes an Info record.
log.warn
Section titled “log.warn”fn warn(logger: Logger, message: String, fields: List<Field> = []) -> Unit
Writes a Warn record.
log.error
Section titled “log.error”fn error(logger: Logger, message: String, fields: List<Field> = []) -> Unit
Writes an Error record.