@std/log.ms#

Import each required symbol with import Name from "@std/log.ms".

LogError Alternative#

Errors returned while validating or writing a structured log record.

Manuscript

type LogError:
    case InvalidInput
    case InvalidData
    case LimitExceeded
    case Closed
    case Io(cause: IoError)
    case FileSystem(cause: FileSystemError)

Manuscript

impl Error for LogError:
    fn message() -> String:

LogError.Closed#

The native transport has closed, so an admitted write or flush cannot complete.

Manuscript

case Closed

LogError.FileSystem#

Opening the owned file transport returned a filesystem error.

Manuscript

case FileSystem(cause: FileSystemError)

LogError.InvalidData#

Structured fields cannot be encoded as valid JSON, including cyclic values.

Manuscript

case InvalidData

LogError.InvalidInput#

The selected record level or an explicit record-size budget is invalid.

Manuscript

case InvalidInput

LogError.Io#

A transport’s underlying byte-stream operation returned its original I/O error.

Manuscript

case Io(cause: IoError)

LogError.LimitExceeded#

The JSON record plus its terminating newline exceeds the supplied byte budget.

Manuscript

case LimitExceeded

LogError.FileSystem.cause#

Original filesystem error retained from file acquisition.

Manuscript

cause: FileSystemError

LogError.Io.cause#

Original stream error; its message and concrete case are preserved.

Manuscript

cause: IoError

LogError.Error.message#

Returns the preserved I/O/filesystem cause message, or a logging-prefixed diagnostic.

Manuscript

fn message() -> String:

LogLevel Alternative#

Severity levels accepted by a logger, ordered from Trace through Fatal.

Manuscript

type LogLevel:
    case Trace
    case Debug
    case Info
    case Warn
    case Error
    case Fatal
    case Silent

LogLevel.Debug#

Development diagnostics, encoded with numeric level 20.

Manuscript

case Debug

LogLevel.Error#

Failure records, encoded with numeric level 50.

Manuscript

case Error

LogLevel.Fatal#

Critical records at numeric level 60; logging does not terminate the process.

Manuscript

case Fatal

LogLevel.Info#

Ordinary operational records, encoded with numeric level 30; the default threshold.

Manuscript

case Info

LogLevel.Silent#

Filtering threshold that disables records; passing it to log returns InvalidInput.

Manuscript

case Silent

LogLevel.Trace#

Most detailed records, encoded with numeric level 10.

Manuscript

case Trace

LogLevel.Warn#

Warning records, encoded with numeric level 40.

Manuscript

case Warn

Logger Interface#

A structured logger with level filtering, bound fields, and pluggable transports.

Manuscript

interface Logger:
    fn log(level: LogLevel, message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn trace(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn debug(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn info(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn warn(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn error(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn fatal(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]
    fn enabled(level: LogLevel) -> Bool
    fn level() -> LogLevel
    fn set_level(level: LogLevel) -> Unit
    fn child(bindings: Map[String, JsonValue]) -> Logger
    fn flush() -> Result[Unit, LogError]

Logger.child#

Returns a logger that adds these fields to each record.

Manuscript

fn child(bindings: Map[String, JsonValue]) -> Logger

Logger.debug#

Logs at Debug when enabled, with call fields overriding child bindings for duplicate keys.

Manuscript

fn debug(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Logger.enabled#

Tests the current filtering threshold; Silent is never enabled as a record level.

Manuscript

fn enabled(level: LogLevel) -> Bool

Logger.error#

Logs at Error when enabled; it records an expected diagnostic rather than raising a fault.

Manuscript

fn error(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Logger.fatal#

Logs at Fatal when enabled; the caller remains responsible for process termination.

Manuscript

fn fatal(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Logger.flush#

Flushes the logger’s transport.

Manuscript

fn flush() -> Result[Unit, LogError]

Logger.info#

Logs at Info when enabled; reserved level, msg, and time fields remain controlled by the logger.

Manuscript

fn info(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Logger.level#

Returns this logger’s current threshold, independent of its parent or children.

Manuscript

fn level() -> LogLevel

Logger.log#

Writes a record at the selected level with optional JSON fields.

Manuscript

fn log(level: LogLevel, message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Logger.set_level#

Changes only this logger’s threshold; existing child loggers retain their copied threshold.

Manuscript

fn set_level(level: LogLevel) -> Unit

Logger.trace#

Logs at Trace when enabled; a filtered call returns ok without encoding or transport access.

Manuscript

fn trace(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Logger.warn#

Logs at Warn when enabled, returning encoding, size-budget, or transport errors unchanged.

Manuscript

fn warn(message: String, fields: Optional[Map[String, JsonValue]] = none) -> Result[Unit, LogError]

Transport Interface#

A destination that accepts encoded log records and can be flushed and closed.

Manuscript

interface Transport:
    fn write(data: Bytes) -> Result[Unit, LogError]
    fn flush() -> Result[Unit, LogError]
    fn close() -> Unit

Transport.close#

Releases owned resources; native close cancels admitted operations and leaves borrowed streams open.

Manuscript

fn close() -> Unit

Transport.flush#

Delegates flush to the destination; persistence and buffering depend on that destination.

Manuscript

fn flush() -> Result[Unit, LogError]

Transport.write#

Accepts encoded record bytes; native transports serialize writes and may return the original I/O cause. Errors can follow a partial external write, without rollback.

Manuscript

fn write(data: Bytes) -> Result[Unit, LogError]

create Function#

Creates a logger. Defaults to Info, no bound fields, timestamps enabled, and no record-size limit.

Manuscript

fn create(transport: Transport, level: Optional[LogLevel] = none, bindings: Optional[Map[String, JsonValue]] = none, timestamp: Optional[Bool] = none, max_bytes: Optional[Int] = none) -> Result[Logger, LogError]:

file_transport Function#

Appends log records to a file at path.

Manuscript

fn file_transport(path: String) -> Result[Transport, LogError]:

stdout_transport Function#

Writes log records to the process standard-output stream.

Manuscript

fn stdout_transport() -> Transport:

stream_transport Function#

Writes log records to an existing byte stream.

Manuscript

fn stream_transport(output: WriteStream) -> Transport: