A straightforward logging library for Gleam.
Dedicated to Echo, my dog.

woof gets out of your way: import it, call info(...), and you're done. When you need more structured fields, namespaces, scoped context. It's all there without changing the core workflow.

gleam add woof

import woof

pub fn main() {
  woof.info("Server started", [#("port", "3000")])
  woof.warning("Cache almost full", [#("usage", "92%")])
}

Output:

[INFO] 10:30:45 Server started
  port: 3000
[WARN] 10:30:46 Cache almost full
  usage: 92%

That's it. No setup, no builder chains, no ceremony.

Every log function accepts a list of #(String, String) tuples. Use the built-in field helpers to skip manual conversion:

import woof

woof.info("Payment processed", [
  woof.field("order_id", "ORD-42"),
  woof.int_field("amount", 4999),
  woof.float_field("tax", 8.5),
  woof.bool_field("express", True),
])

Plain tuples still work if you prefer — the helpers are just convenience:

woof.info("Request", [#("method", "GET"), #("path", "/api")])

Available helpers: field, int_field, float_field, bool_field.

Four levels, ordered by severity:

Set the minimum level to silence the noise:

woof.set_level(woof.Warning)

woof.debug("ignored", [])      // dropped — below Warning
woof.info("also ignored", [])  // dropped
woof.warning("shown", [])      // printed
woof.error("shown too", [])    // printed

Human-readable, great for development.

woof.set_format(woof.Text)

[INFO] 10:30:45 User signed in
  user_id: u_123
  method: oauth

Machine-readable, one object per line — ideal for production and tools like Loki, Datadog, or CloudWatch.

woof.set_format(woof.Json)

{"level":"info","time":"2026-02-11T10:30:45.123Z","msg":"User signed in","user_id":"u_123","method":"oauth"}

Plug in any function that takes an Entry and returns a String. This is the escape hatch for integrating with other formatting or output libraries.

let my_format = fn(entry: woof.Entry) -> String {
  woof.level_name(entry.level) <> " | " <> entry.message
}

woof.set_format(woof.Custom(my_format))

Single-line, key=value pairs — a compact middle ground.

woof.set_format(woof.Compact)

INFO 2026-02-11T10:30:45.123Z User signed in user_id=u_123 method=oauth

Organise log output by component without polluting the message itself.

let log = woof.new("database")

log |> woof.log(woof.Info, "Connected", [#("host", "localhost")])
log |> woof.log(woof.Debug, "Query executed", [#("ms", "12")])

[INFO] 10:30:45 database: Connected
  host: localhost
[DEBUG] 10:30:45 database: Query executed
  ms: 12

In JSON output the namespace appears as the "ns" field.

Attach fields to every log call inside a callback. Perfect for request-scoped metadata.

use <- woof.with_context([#("request_id", req.id)])

woof.info("Handling request", [])   // includes request_id
do_work()
woof.info("Done", [])              // still includes request_id

On the BEAM each process (= each request handler) gets its own context via the process dictionary, so concurrent handlers never interfere.

Nesting works — inner contexts accumulate on top of outer ones:

use <- woof.with_context([#("service", "api")])
use <- woof.with_context([#("request_id", id)])

woof.info("Processing", [])
// fields: service=api, request_id=<id>

Notice for JavaScript async users
On the BEAM, with_context uses the process dictionary, so concurrent requests never interfere. On the JavaScript target, because JS is fundamentally single-threaded with cooperative concurrency, with_context modifies a global state. If your with_context callback returns a Promise (or does asynchronous awaits), the context might leak or be overwritten by other concurrent async operations. If you heavily rely on async/await in Node/Deno for concurrent requests, consider passing context explicitly instead of using with_context.

Set fields that appear on every message, everywhere:

woof.set_global_context([
  #("app", "my-service"),
  #("version", "1.2.0"),
  #("env", "production"),
])

For one-shot setup, use configure:

woof.configure(woof.Config(
  level: woof.Info,
  format: woof.Json,
  colors: woof.Auto,
))

Or change individual settings:

woof.set_level(woof.Info)
woof.set_format(woof.Json)
woof.set_colors(woof.Never)

Colors apply to Text format only. Three modes:

• Auto (default) — colors are enabled when stdout is a TTY and NO_COLOR is not set.
• Always — force ANSI colors regardless of environment.
• Never — plain text, no escape codes.

woof.set_colors(woof.Always)

Level colors: Debug → dim grey, Info → blue, Warning → yellow, Error → bold red.

When building the log message is expensive, use the lazy variants. The thunk is only called if the level is enabled.

woof.debug_lazy(fn() { expensive_debug_dump(state) }, [])

Available: debug_lazy, info_lazy, warning_lazy, error_lazy.

Log and pass a value through — fits naturally in pipelines:

fetch_user(id)
|> woof.tap_info("Fetched user", [])
|> transform_user()
|> woof.tap_debug("Transformed", [])
|> save_user()

Available: tap_debug, tap_info, tap_warning, tap_error.

Log only when a Result is Error, then pass it through:

fetch_data()
|> woof.log_error("Fetch failed", [#("endpoint", url)])
|> result.unwrap(default)

Measure and log the duration of a block:

use <- woof.time("db_query")
database.query(sql)

Emits: db_query completed with a duration_ms field.

woof works on both the Erlang and JavaScript targets.

• Erlang: global state uses persistent_term (part of erts, always available). Scoped context lives in the process dictionary.
• JavaScript: module-level variables. Safe because JS is single-threaded.

Output format is identical on both targets.

• Gleam 1.14 or newer (tested with 1.14.0).
• OTP 22+ on the BEAM (CI uses OTP 28).
• Just gleam_stdlib — no runtime dependencies.

Made with Gleam 💜