Skip to content
Protos

std:logging/Logger

std:logging/Logger

Section titled “std:logging/Logger”

Canonical occurrence: protos/lib/logging/Logger.protos · Protos revision: e99b712ecf658a527b1fe82c8beba2c1286d8dc9.

Explicit structured loggers. A logger is a frozen ordinary object holding a minimum level, a sink, and context fields; it is created and passed around explicitly like any other value. There is no global or default logger, no registry, no mutable configuration, and no thread-, Task-, or dynamically scoped context. A logger opens no stream, file, or connection, reads no ambient clock, and starts no Task.

Time is an explicit capability: a logger created with a time source, a zero-argument callable answering a std:datetime/Instant, stamps each enabled event with the instant that source answers; a logger without one emits events whose timestamp is null. The source is invoked exactly once per enabled call, after its fields are merged and before the event is created, and never for a disabled call or a derivation. An Error signalled by the source, or a result that is not an instant, signals an Error from the logging call before anything is emitted; it is not contained like a sink failure.

A sink is any object answering emit(event); it is the only output authority a logger uses and it receives each enabled std:logging/LogEvent synchronously. An Error signalled by emit is contained by the logging call: it does not reach the caller, is not retried, and is not reported anywhere else. No order is promised between events emitted concurrently through loggers sharing a sink.

Level filtering happens first: a call whose level is less severe than the minimum level answers null after validating only its level, without inspecting its other arguments, copying data, reading the time source, creating an event, or invoking the sink. Callers avoid building expensive data for disabled levels with isEnabled(level).

Context and call-site fields merge by key: a derived logger’s fields override its base logger’s fields, and call-site fields override both.

Observable top-level slots

Section titled “Observable top-level slots”

This page lists the complete mechanically observable top-level slot inventory required by D067. Authored documentation, when present, is canonical D062 prose; mechanical presence alone does not create a stability or compatibility promise.

call

Section titled “call”

Answers a fresh frozen logger that emits events at least as severe as minimumLevel to sink, stamped with times from timeSource, and has no context fields. minimumLevel must be a canonical level and sink must not be null; otherwise an Error is signalled. timeSource is a zero-argument callable answering a std:datetime/Instant, or null, the default, for events without a timestamp; it is not invoked here. The logger keeps the time source privately, since a slot holding a callable would invoke it on access.

The logger answers:

  • isEnabled(level): whether level is at least minimumLevel.
  • log(level, message), log(level, message, fields), and log(level, message, fields, error): when enabled, emits a std:logging/LogEvent whose fields are the logger’s context merged with fields (a Map, or null for none), whose error is error (an Error, or null), and whose timestamp is the result of one timeSource() call (null without a time source); answers null. Invalid enabled arguments and a failing time source signal an Error.
  • trace, debug, info, warn, and error: log at that level with the remaining arguments.
  • with(fields): a derived logger with the same minimum level, sink, and time source whose context is this logger’s context overridden by a snapshot of the Map fields. The receiver is unchanged.

Mechanical facts

Section titled “Mechanical facts”

Exact module source · Standard-library API · Standard library overview