Next: (scriba syslog), Previous: (scriba layout), Up: API
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.
Thread/fiber-safe contextual tracing data can be appended dynamically using the ‘with-log-context‘ and ‘with-log-tags‘ macros.
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.
Dynamically append CTX (an alist) to the current log context for the duration of BODY.
Dynamically append TAGS (a list) to the current log tags for the duration of BODY.
Default value:
()
Default value:
()
Default value:
()
Default value:
#t
Default value:
trailing
Default value:
(level tags time name message context)
Default value:
info
Default value:
console
Default value:
#<output: file 1>
Default value:
()
Default value:
"%F %T %Z"
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.
Is log level A allowed in a B context?
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.
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.
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.
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.
Emits a log.
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.
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.
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.
Creates a logger, mapping excluded log levels and non-matching tags to log-unit.
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‘.
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.
Is FIELD something a logger knows how to render?
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.
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.
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.
"%F %T %Z"
"%Y-%m-%dT%H:%M:%S%z"
(level tags time host name message context)
"%F %T %z"
(trace debug info success warning error critical)
(level tags time host name process-id message-id context message)
(level tags time host name context message)
Next: (scriba syslog), Previous: (scriba layout), Up: API