1 API

The following is the list of modules provided by this library. The stylesheet and the script that present this chapter in a browser are written beside it, as dokgen.css and dokgen.js; the manual says how a build points at them.


1.1 (scriba auto)

This module provides zero-configuration initialization for the Scriba logging framework. It dynamically bootstraps, configures, and memoizes an appropriate logger backend based on system environment variables.

1.1.1 Overview

1.1.2 Procedures

Procedure: %make-scriba-auto-logger KEY: #:name #:level #:context-filter #:tag-filter #:out-port #:timestamp-format #:flush-port? #:pretty? #:layout #:line-ending #:path #:max-size #:max-backups #:log-format

Creates a logger automatically configured by environment variables.

Each backend only receives the keywords it understands: the file backend takes a path and rotation options instead of an output port, and syslog keeps its own RFC 5424 layout.

Procedure: scriba-auto-logger . kwargs

Undocumented procedure.


1.2 (scriba color-console)

This module provides an interactive console logger utilizing ANSI escape sequences to colorize terminal output. Text elements are visually prioritized by log severity levels, while metadata blocks are systematically dimmed.

1.2.1 Overview

1.2.2 Procedures

Procedure: %make-scriba-color-console-logger KEY: #:name #:level #:context-filter #:tag-filter #:timestamp-format #:out-port #:flush-port? #:layout #:line-ending

Undocumented procedure.

Procedure: scriba-color-console-logger . kwargs

Undocumented procedure.


1.3 (scriba console)

This module provides a standard plaintext, uncolorized console logging backend for the Scriba logging framework. It outputs logs cleanly structured by brackets, making it optimal for production log-aggregation sidecars, file appending, or basic interactive terminal sessions.

1.3.1 Overview

1.3.2 Procedures

Procedure: %make-scriba-console-logger KEY: #:name #:level #:context-filter #:tag-filter #:timestamp-format #:out-port #:flush-port? #:layout #:line-ending

Undocumented procedure.

Procedure: scriba-console-logger . kwargs

Undocumented procedure.


1.4 (scriba exception)

Turning a Guile exception into something a log line can carry.

A Guile exception is a key plus arguments: ‘car’ raising ‘wrong-type-arg’, ‘error’ raising ‘misc-error’, ‘(throw ’app-error ...)’ raising ‘app-error’. Rendering that well is Guile’s own job - ‘print-exception’ knows every key’s message shape, including the strerror text of a system error and the location of a syntax error - so the message here is exactly what Guile would print, without reimplementing any of those cases.

What Guile does not lend is the trace, and that is what makes an exception legible in a log: a handler installed before unwinding still has the frames that raised, and the report keeps them as ‘at NAME (FILE:LINE)’ lines, innermost first, with Guile’s own machinery and this module’s plumbing dropped. Backends then render as much of the report as their destination can carry: the text backends indent the trace under the message, JSON makes an object of it, and syslog, which frames one message per line, joins it with separators.

1.4.1 Overview

1.4.2 Macros

Macro: exception-report-message x

Undocumented macro.

Macro: exception-report-trace x

Undocumented macro.

Macro: exception-report-type x

Undocumented macro.

Macro: exception-report? x

Undocumented macro.

Macro: with-exception-logging x

Logs an exception raised by BODY on LOGGER, then re-raises it.

(with-exception-logging log
  (process-request request))

1.4.3 Procedures

Procedure: call-with-exception-log logger thunk KEY: #:level #:depth

Calls THUNK, logging an exception it raises before re-raising it.

The handler runs before the stack is unwound, so ‘(make-stack #t 2)’ still holds the frames that raised; an unwinding handler would see only its own.

A ‘quit’ - how a Scheme program leaves - is passed on unlogged: exiting is not a failure to report. Logging must never hide the failure it reports, so a log statement that itself raises is swallowed, and the original exception still propagates with the same key and arguments it arrived with.

Procedure: format-exception-line report

Returns REPORT on one line, for backends that frame one message per line.

Procedure: format-exception-trace report KEY: #:indent

Returns the trace of REPORT indented for a text backend, or the empty string.

Procedure: log-exception logger report KEY: #:level

Logs REPORT on LOGGER at LEVEL, leaving the rendering to the backend.

The report is bound to ‘current-log-exception’ around the call, which is what each backend reads to indent the trace, nest it in JSON, or flatten it onto one line. The message of the report is the log message itself, so a logger’s level, tag and context filters apply to an exception as they do to any other line.

Procedure: make-exception-report key args KEY: #:stack #:depth

Summarises the exception KEY and ARGS, with a trace of STACK.

STACK is what a handler installed before unwinding captures with ‘(make-stack #t 2)’. Without one the report still carries the type and the message, and only the trace is missing.


1.5 (scriba file)

This module implements a plaintext file logging backend with size based rotation. Log lines keep the same bracketed layout as the console backend, so a file written by Scriba can be tailed, grepped and shipped by log aggregators without any transformation.

Rotation happens when the next line would push the file past ‘#:max-size’ bytes. The current file is renamed to ‘<path>.1’, older backups are shifted up, and the oldest backup beyond ‘#:max-backups’ is removed. As a result a file never grows past ‘#:max-size’ unless a single line is larger than it. Setting ‘#:max-size’ to #f disables rotation entirely, and ‘#:max-backups’ to 0 keeps no history (the file is simply truncated). ‘rotate-file!’ rotates on demand, for example from a SIGHUP handler or a cron job.

One sink, meaning one open port and one rotation policy, is kept per path. Loggers created for the same path share it, which keeps independent loggers (say one for ‘app’ and one for ‘db’) from fighting over rotation and from reopening the file on every message. Rotation is a property of the file rather than of a logger, so when a later logger asks for a different policy on the same path, that policy takes over for everyone.

1.5.1 Overview

1.5.2 Parameters

Parameter: default-file-max-backups

Default value:

5
Parameter: default-file-max-size

Default value:

10485760
Parameter: default-file-path

Default value:

#f

1.5.3 Procedures

Procedure: %make-scriba-file-logger KEY: #:path #:name #:level #:context-filter #:tag-filter #:timestamp-format #:flush-port? #:layout #:line-ending #:max-size #:max-backups

Creates a logger appending lines to the file at PATH.

PATH is required (there is no sensible default file) and its parent directory must already exist. MAX-SIZE and MAX-BACKUPS control rotation, see the module commentary.

Procedure: file-sink-open? path

Is a Scriba file sink currently open for PATH?

Procedure: rotate-file! path

Rotates PATH right now, returning #t.

PATH must be a path that a Scriba file logger has already opened; that is what makes the open port and the rotated files agree on which file is current.

Procedure: scriba-file-logger . kwargs

Undocumented procedure.


1.6 (scriba json)

This module implements a structured JSON logging backend for the Scriba framework using Guile’s (json) module serialization. It is intended for production environments that require schema-compliant logs ready to be parsed by log shippers and indexers (e.g., Loki, Elasticsearch, Logstash, Fluentd).

1.6.1 Overview

1.6.2 Parameters

Parameter: default-json-pretty?

Default value:

#f

1.6.3 Procedures

Procedure: %make-scriba-json-logger KEY: #:name #:level #:context-filter #:tag-filter #:pretty? #:timestamp-format #:out-port #:flush-port? #:line-ending #:layout

Undocumented procedure.

Procedure: scriba-json-logger . kwargs

Undocumented procedure.


1.7 (scriba layout)

This module holds the plaintext layout shared by Scriba’s text backends (the console and the file logger). Fields are formatted as bracketed blocks and joined in the order requested by the logger’s ‘#:layout‘, so a backend only has to decide where the finished line goes.

Timestamps are cached per format string and per wall-clock second. Formatting a time is by far the most expensive part of a log line (it consults the timezone database), while a second-resolution format cannot change within the same second, so the cache removes that cost from every line but the first one of each second.

1.7.1 Overview

  • display->string — Returns VALUE rendered the way ‘display’ would render it.
  • format-context — Converts an alist context into a bracketed string layout: [k=v] [k=v].
  • format-name — Returns the formatted logger name, or an empty string.
  • format-plain-time — Returns the current time formatted with FORMAT-STRING, without brackets.
  • format-tags — Converts an list of tags into a bracketed string layout: [#a #b #c].
  • format-timestamp — Returns a formatted, bracketed timestamp string.
  • make-text-printer — Returns a procedure that turns a log level into a logging procedure.

1.7.2 Procedures

Procedure: display->string value

Returns VALUE rendered the way ‘display’ would render it.

Strings are returned untouched, so the common case allocates nothing.

Procedure: format-context ctx

Converts an alist context into a bracketed string layout: [k=v] [k=v].

Procedure: format-name name

Returns the formatted logger name, or an empty string.

Procedure: format-plain-time format-string

Returns the current time formatted with FORMAT-STRING, without brackets.

The result is reused for every log line within the same second, because strftime and localtime are much more expensive than the rest of a log line and a second-resolution format cannot change faster than that.

Procedure: format-tags tags

Converts an list of tags into a bracketed string layout: [#a #b #c].

Procedure: format-timestamp format-string

Returns a formatted, bracketed timestamp string.

Procedure: make-text-printer KEY: #:name #:layout #:timestamp-format #:emit

Returns a procedure that turns a log level into a logging procedure.

The returned procedure maps a level symbol (or #t for level-less messages) to a ‘(lambda (msg . args) ...)’ procedure. When called, that procedure formats MSG with ARGS, builds the configured LAYOUT and hands the finished line, without any newline, to EMIT. Backends use EMIT to choose their destination, newline placement and flushing behaviour.

A line logged for an exception - see ‘(scriba exception)’ - carries the report’s trace indented under it, because a text destination has room for the frames that JSON and syslog have to fold into fields.


1.8 (scriba scriba)

This is the fundamental engine core for the Scriba logging framework. It manages internal logger records, logging level severities, dynamic execution context (MDC), optimization shortcuts, and global configuration parameters.

To minimize execution overhead from muted logs in high-throughput loops, Scriba uses a level filtering system at instantiation time (‘make-filtered-logger‘). If a severity level falls below the configured threshold, its logging procedure is bound directly to a zero-overhead no-op function (‘log-unit‘). This avoids unnecessary runtime level checks during iterative logging calls.

Mermaid diagram, as source:

flowchart LR
  call["log-info, log-error, ..."] --> filter["maybe-log-proc<br/>level, tag and context filters"]
  filter -- "muted level or filters miss" --> noop["log-unit, a no-op"]
  filter -- "allowed" --> format["format-log-message<br/>rendered by the logger's layout"]
  format --> write["write-log-line<br/>framed with its line ending"]
  write --> port[("a port: console, JSON, file or syslog")]

Thread/fiber-safe contextual tracing data can be appended dynamically using the ‘with-log-context‘ and ‘with-log-tags‘ macros.

1.8.1 Overview

1.8.2 Macros

Macro: memoize-logger x

Wraps a logger FACTORY-PROC with a caching layer.

Returns a new variadic procedure that accepts arbitrary keyword arguments (KWARGS). When called, it checks a private hash table to see if a logger has already been instantiated with the exact same configuration. If so, it returns the cached instance. If not, it calls FACTORY-PROC, caches the resulting logger, and returns it.

The optional (KW THUNK) pairs declare the defaults that FACTORY-PROC derives from dynamically scoped parameters. Their current values are evaluated on every call and merged into the cache key (unless the caller passed KW explicitly), so parameterized defaults such as ‘default-out-port‘ correctly produce distinct loggers.

Macro: with-log-context x

Dynamically append CTX (an alist) to the current log context for the duration of BODY.

Macro: with-log-tags x

Dynamically append TAGS (a list) to the current log tags for the duration of BODY.

1.8.3 Parameters

Parameter: current-log-context

Default value:

()
Parameter: current-log-exception

Default value:

#f
Parameter: current-log-tags

Default value:

()
Parameter: default-context-filter

Default value:

()
Parameter: default-flush-port?

Default value:

#t
Parameter: default-line-ending

Default value:

trailing
Parameter: default-log-layout

Default value:

(level tags time name message context)
Parameter: default-log-level

Default value:

info
Parameter: default-logger

Default value:

console
Parameter: default-out-port

Default value:

#<output: file 1>
Parameter: default-tag-filter

Default value:

()
Parameter: default-time-format

Default value:

"%F %T %Z"

1.8.4 Procedures

Procedure: format-log-message msg args

Applies MSG as a format string to ARGS, skipping the formatter for no ARGS.

Most log statements carry a literal message and no arguments, and Guile’s formatter is comparatively expensive, so a string is passed through untouched when there is nothing to substitute. Messages with arguments are formatted as usual. A side effect is that a lone message containing ‘~’ is now literal instead of being interpreted as a (likely invalid) format directive.

Procedure: is-in-log-level? a b

Is log level A allowed in a B context?

Procedure: log-critical logger message . args

Emits a CRITICAL level log.

Use this for severe, unrecoverable failures that usually require immediate attention, cause data loss, or force the application to abort. MESSAGE is a format string applied to the optional ARGS.

Procedure: log-debug logger message . args

Emits a DEBUG level log.

Use this for diagnostic information helpful to developers when troubleshooting, but generally too noisy to be left enabled in production environments. MESSAGE is a format string applied to the optional ARGS.

Procedure: log-error logger message . args

Emits an ERROR level log.

Use this to record failed operations or exceptions that prevent a specific task from completing, even if the application as a whole can continue running. MESSAGE is a format string applied to the optional ARGS.

Procedure: log-info logger message . args

Emits an INFO level log.

Use this to highlight the normal, high-level progression of the application, such as service startups, configuration loads, or periodic heartbeat events. MESSAGE is a format string applied to the optional ARGS.

Procedure: log-message logger message . args

Emits a log.

Procedure: log-success logger message . args

Emits a SUCCESS level log.

Use this to explicitly indicate the successful completion of a significant operation, task, or transaction. MESSAGE is a format string applied to the optional ARGS.

Procedure: log-trace logger message . args

Emits a TRACE level log.

Use this for the most fine-grained, verbose informational events, such as step-by-step execution traces, loops, or variable dumps. MESSAGE is a format string applied to the optional ARGS.

Procedure: log-warning logger message . args

Emits a WARNING level log.

Use this to flag unexpected or potentially harmful situations that the application can gracefully recover from, such as deprecated API usage or temporary network retries. MESSAGE is a format string applied to the optional ARGS.

Procedure: make-filtered-logger KEY: #:name #:level #:context-filter #:tag-filter #:log-message-proc #:log-trace-proc #:log-debug-proc #:log-info-proc #:log-success-proc #:log-warning-proc #:log-error-proc #:log-critical-proc

Creates a logger, mapping excluded log levels and non-matching tags to log-unit.

Procedure: maybe-log-proc KEY: #:level #:target-level #:context-filter #:tag-filter #:proc

Conditionally evaluate and compile a logging procedure based on severity, tags, and context.

Compares TARGET-LEVEL against the logger’s configured LEVEL. If the level is explicitly disabled or falls below the required threshold, this returns the ‘log-unit‘ no-op procedure directly, avoiding downstream runtime overhead.

If the severity level is active, it returns a higher-order wrapper closure. When invoked, this closure inspects fluid parameters via ‘(current-log-tags)‘ and ‘(current-log-context)‘. If both constraints match their filters, it delegates formatting to PROC; otherwise, it safely routes execution to the no-op ‘log-unit‘.

Procedure: tag-match? filter-tags current-tags

Determine if the current execution context satisfies the logger’s tag filter. Returns #t if FILTER-TAGS is empty (acting as a wildcard), or if there is a lenient intersection (cross-comparing strings, symbols, and numbers) of at least one element between FILTER-TAGS and CURRENT-TAGS.

Procedure: valid-log-field? field

Is FIELD something a logger knows how to render?

Procedure: valid-log-level? level

Is LEVEL a log level that Scriba understands?

#t means "always log", #f means "never log", and every symbol in ‘log-levels‘ is a real severity.

Procedure: validate-log-layout layout KEY: #:fields

Raise a descriptive error when LAYOUT is not a usable layout for a backend.

A mistyped field name used to be dropped silently, which turned a misconfigured logger into one that writes blank lines. Failing at construction time instead makes the typo impossible to miss.

Procedure: write-log-line port line line-ending

Frames LINE with a newline and writes it to PORT.

LINE-ENDING decides where that newline goes: ’trailing (the default) appends it, so log lines behave like ordinary text lines and the stream never starts with a blank line. ’leading prepends it, which is handy when the log stream is interleaved with prompts or other output that lacks a final newline.

‘display’ and ‘newline’ are used instead of ‘format’ because a format call costs an order of magnitude more than the rest of a short log line.

1.8.5 Variables

Variable: human-time-format
"%F %T %Z"
Variable: iso-8601-time-format
"%Y-%m-%dT%H:%M:%S%z"
Variable: json-layout-fields
(level tags time host name message context)
Variable: log-friendly-time-format
"%F %T %z"
Variable: log-levels
(trace debug info success warning error critical)
Variable: syslog-layout-fields
(level tags time host name process-id message-id context message)
Variable: text-layout-fields
(level tags time host name context message)

1.9 (scriba syslog)

This module implements a logging backend structured to conform with syslog protocol specifications (such as RFC 5424 concepts). It generates string messages featuring priority framing headers, process identifier tracking, and standardized structured metadata fields.

1.9.1 Overview

1.9.2 Parameters

Parameter: default-syslog-time-format

Default value:

"%Y-%m-%dT%H:%M:%S%z"

1.9.3 Procedures

Procedure: %make-scriba-syslog-logger KEY: #:name #:level #:context-filter #:tag-filter #:timestamp-format #:out-port #:flush-port? #:line-ending #:layout

Undocumented procedure.

Procedure: scriba-syslog-logger . kwargs

Undocumented procedure.