silk.io.logger.

When to use#

Require &mut Logger in code that logs, and call Effect.logInfo, Effect.logWarning, and the other Effect.log... functions. The program decides where the messages go when it provides the logger: silk.io.logger_native.StderrLogger for a native program, or InMemoryLogger in a test.

Details#

Each call has a LogLevel, a template that is known at compile time, and a borrowed tuple or record of values. The template rules are those of silk.text.format.Format.format. The provider formats the message and decides about newlines, timestamps, and prefixes. The caller does not need a Writer or an Allocator.

InMemoryLogger keeps at most eight messages and 64 message bytes in total. It counts calls that failed separately from messages that it kept.

Errors#

• LogError if the provider cannot log the message. The message was not necessarily logged.

Gotchas#

The accessors of InMemoryLogger need an event index less than Logger.length and a byte index less than the message length.

Examples#

Log a warning and check it in a test#

import silk.core.effect { Effect }
import silk.io.logger { LogError, LogLevel, Logger }

pub effect fn main() -> i32
  ! LogError {
  let mut logger = Logger.inMemoryProvider()
  let values = .{ kind: "users", count: 3 }
  run Effect.logWarning("cache {kind} missed {count} times", &values)
    |> Effect.provideMut<Logger>(&mut logger)
  if Logger.length(&logger) != 1 || Logger.levelAt(&logger, 0) != LogLevel.Warning {
    return 1
  }
  if Logger.messageLengthAt(&logger, 0) != 26 {
    return 1
  }
  return 0
}

Import as Logger with import silk.io.logger { Logger }.

Public declarations: 4.

LogLevel#

pub enum LogLevel

The level of a log message, from Trace (most detail) to Error (most serious).

Trace#

Trace

Very detailed messages to trace a problem.

Debug#

Debug

Messages that help during development.

Info#

Info

Normal events in the operation of the program.

Warning#

Warning

A problem that the program recovered from.

Error#

Error

An operation that did not complete as intended.

LogError#

pub struct LogError

The error when a logger provider cannot log a message.

Details#

It has a code that the provider defines. Get it with Logger.errorCode. The same code can mean different things for different providers.

Implementation Debug for LogError#

impl Debug for LogError

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the code, as LogError { code: ... }.

Logger#

pub service Logger

The effect that receives log messages with a level, a template, and values.

When to use#

Require &mut Logger in code that logs, and call Effect.logInfo, Effect.logWarning, and the other Effect.log... functions. The program decides where the messages go when it provides the logger: silk.io.logger_native.StderrLogger for a native program, or InMemoryLogger in a test.

Details#

The caller does not need a Writer or an Allocator. A provider implements log. It formats the message with the rules of silk.text.format and decides where it goes and what decoration it gets, such as a newline or a timestamp.

Operation log#

effect fn log<Args>(
    level: LogLevel,
    static template: string<'static>,
    args: &Args
  ) -> () ! LogError ? &mut Logger

Formats template with args and logs it at level.

Details#

The template rules are those of silk.text.format.Format.format, and the compiler checks them. The call adds no newline, level label, or timestamp. The provider can add them.

Errors#

• LogError if the provider cannot log the message.

Implementation Logger#

impl Logger

Associated function failure#

pub fn failure(code: i32) -> LogError

Creates a logging failure with a provider-defined code.

Associated function errorCode#

pub fn errorCode(error: LogError) -> i32

Returns the provider-defined failure code for diagnostics.

Gotchas#

Interpret this code only with knowledge of the selected provider. Different providers can use the same code for different failures.

Associated function inMemoryProvider#

pub fn inMemoryProvider() -> InMemoryLogger

Creates an empty in-memory logger with capacity for eight events and 64 message bytes.

Gotchas#

A call fails when eight events are already committed. A call also fails when its bytes exceed the remaining 64-byte total. Neither failure commits the event.

Associated function inMemoryProviderFailAt#

pub fn inMemoryProviderFailAt(failAt: usize) -> InMemoryLogger

Creates an in-memory logger that rejects one zero-based attempted-call ordinal.

Details#

The configured attempt increases attempts but does not increase length or consume message capacity. Other attempts retain the eight-event and 64-byte limits of inMemoryProvider.

Method length#

pub fn length(self: &InMemoryLogger) -> usize

Returns the number of events that the in-memory logger committed.

Details#

Failed attempts do not increase this count. Use Logger.attempts when rejected calls must also be observed.

Method levelAt#

pub fn levelAt(self: &InMemoryLogger, index: usize) -> LogLevel

Returns the severity of one committed event.

Gotchas#

index must be less than length. An unused index below eight returns the initial Trace value instead of trapping. An index of eight or more traps.

Method messageLengthAt#

pub fn messageLengthAt(self: &InMemoryLogger, index: usize) -> usize

Returns the UTF-8 byte length of one committed message.

Gotchas#

index must be less than length. An unused index below eight returns zero instead of trapping. An index of eight or more traps.

Method messageByteAt#

pub fn messageByteAt(
    self: &InMemoryLogger,
    eventIndex: usize,
    byteIndex: usize
  ) -> u8

Returns one UTF-8 byte from a committed message.

Gotchas#

eventIndex must be less than length. byteIndex must be less than messageLengthAt for that event. An unused event or invalid byte index traps. An event index of eight or more also traps.

Method attempts#

pub fn attempts(self: &InMemoryLogger) -> usize

Returns the number of calls attempted, including calls that produced LogError.

InMemoryLogger#

pub struct InMemoryLogger

A deterministic Logger provider that retains up to eight events and 64 total message bytes.

When to use#

Use this provider in tests that must inspect event order, severity, message bytes, or failure behavior without process output.

Details#

The provider copies each committed message into fixed internal storage. It records attempted calls separately from committed events. Capacity failure and configured failure do not commit an event.

Gotchas#

The accessors need an event index less than Logger.length and a byte index less than the message length.

Implementation InMemoryLogger#

impl InMemoryLogger

Implementation Logger for InMemoryLogger#

impl Logger for InMemoryLogger

Operation log#

log: InMemoryLogger.record

Category: Input and output.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.