jjba23/scriba: A Lisp structured logging library with flexibility, performance and configuration in mind, powered by Guile Scheme. - Codeberg.org
This website requires JavaScript.
jjba23/scriba
Watch
Star
Fork
You've already forked scriba
Code
Issues
Pull requests
Activity
A Lisp structured logging library with flexibility, performance and configuration in mind, powered by Guile Scheme.
29 commits
1 branch
3 tags
172 KiB
Scheme
100%
trunk
Find a file
HTTPS
Download ZIP<br>Download TAR.GZ<br>Download BUNDLE
Open with VS Code
Open with VSCodium
Open with Intellij IDEA
Josep Bigorra
156d3480df
All checks were successful
ci/woodpecker/tag/byggsteg Pipeline was successful
Details
ci/woodpecker/push/byggsteg Pipeline was successful
Details
docs: 📝
2026-05-24 11:25:50 +02:00
.woodpecker
feat: ✨ Initialize repo
2026-05-22 09:46:00 +02:00
src/scriba
docs: 📝
2026-05-24 11:21:46 +02:00
test/veritas/unit
feat: ✨ Add auto-logger
2026-05-24 10:59:22 +02:00
.gitignore
feat: ✨ Initialize repo
2026-05-22 09:46:00 +02:00
COPYING
feat: ✨ Initialize repo
2026-05-22 09:46:00 +02:00
maak.scm
feat: ✨ Improve JSON logger
2026-05-23 13:26:21 +02:00
manifest.scm
fix: 🔧 Remove logger re-export
2026-05-22 22:58:22 +02:00
README.org
docs: 📝
2026-05-24 11:25:50 +02:00
README.org
scriba
Why Scriba?
Quickstart
The Auto-Configured Logger
Environment Configuration
Core Concepts
Specific Loggers
Log Levels
Log Context
Runtime Dependencies
Licensing
Code of conduct
Scriba Project
A Lisp structured logging library with flexibility, performance and configuration in mind, powered by Guile Scheme.
If you like my work, please support me by buying me a cup of coffee ☕ so I can continue with a lot of motivation.
Why Scriba?
A primary advantage of Scriba over standard display, write, or println procedures is fine-grained control over log routing, formatting and filtering, with the addition of structured context in logs.
By separating formatting, severity levels, and output destinations, Scriba offers modularity that makes extending the library or writing your own custom loggers trivial.
Scriba is built around the core abstraction of a logger . It achieves high performance by memoizing computations and leveraging compile-time macro expansions (see scriba.scm.
Find the complete, technical Guile Scheme API documentation here
Quickstart
The Auto-Configured Logger
While you can instantiate specific loggers manually, the simplest way to get started is with the auto-logger . It reads environment variables (and, in the future, Scheme configuration files) to automatically determine at runtime which logger to use and how to configure it.
This is especially useful for maintaining different logging behaviors between development and production environments. A common use-case is to use a pretty and colorful console logger in local development, and structured JSON logging in production, for logs to be parsed and aggregated by tools like Loki.
(define-module (my-module)<br>#:use-module (scriba auto)<br>#:use-module (scriba scriba))
(let* ((s (scriba-auto-logger)))<br>(log-info s "Hello Scriba!")<br>(with-log-context `((key-1 . value-1))<br>(log-info s "Message with context")))
Example console logging:
[INFO] [2026-05-24 11:23:06 CEST] Hello Scriba, 2 + 2 = 4!<br>[INFO] [2026-05-24 11:23:06 CEST] [sample-1=value-1] Some log with context
Example JSON logging:
{"level":"INFO","time":"2026-05-24 11:23:06 CEST","message":"Some log with context","sample-2":"value-2"}<br>{"level":"WARNING","time":"2026-05-24 11:23:06 CEST","message":"some kind of warning"}
Note: Logger creation is memoized. Subsequent calls to create the same logger (even elsewhere in your codebase) are instant because the result is only computed once.
Environment Configuration
The auto-logger checks for SCRIBA_ prefixed environment variables first (allowing application-specific overrides) before falling back to standard LOG_ variables.
Scriba Env Var<br>Standard Env Var<br>Description<br>Default
SCRIBA_LOGGER<br>LOGGER<br>The logger backend to use (console or json).<br>console
SCRIBA_LOG_LEVEL<br>LOG_LEVEL<br>Minimum severity level (e.g., debug, info, error).<br>info
SCRIBA_JSON_PRETTY<br>LOG_JSON_PRETTY<br>Set to true or 1 to pretty-print JSON logs.<br>#f
SCRIBA_WITH_TIMESTAMP<br>LOG_WITH_TIMESTAMP<br>Set to true or 1 to include timestamps.<br>#t
SCRIBA_TIMESTAMP_FORMAT<br>LOG_TIMESTAMP_FORMAT<br>The strftime format string (e.g., "%F %T %z").<br>"%F %T %Z"
Because in its implementation, the get-env-* functions act as defaults for the #:key arguments in %make-scriba-auto-logger, you can easily override the environment programmatically: (scriba-auto-logger #:level 'trace).
Core Concepts
Specific Loggers
Loggers are (optionally named) entities responsible for emitting logs. They act as the primary interface between your application and Scriba. If you prefer to have more control and bypass the auto-logger, you can instantiate specific loggers directly.
Console Logger:
(use-module...