viva_telemetry - v1.0.1

viva_telemetry/log

viva_telemetry/log - Structured logging for Gleam

Inspired by: structlog (Python), zap (Go), tracing (Rust)

Features

Quick Start

import viva_telemetry/log

pub fn main() {
  // Simple logging
  log.info("Server started", [#("port", "8080")])

  // With context
  log.with_context([#("request_id", "abc123")], fn() {
    log.debug("Processing request", [])
  })
}

Values

add_handler

</> 
pub fn add_handler(handler: handler.Handler) -> Nil

Add a handler to the existing configuration

alert

</> 
pub fn alert(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at alert level

alert_lazy

</> 
pub fn alert_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy alert

alert_level

</> 
pub const alert_level: level.Level

Alert level (action must be taken immediately)

bind_context

</> 
pub fn bind_context(context: List(#(String, String))) -> Nil

Add context fields that persist for this process

clear_context

</> 
pub fn clear_context() -> Nil

Clear all context

configure

</> 
pub fn configure(handlers: List(handler.Handler)) -> Nil

Configure global handlers

configure_console

</> 
pub fn configure_console(lvl: level.Level) -> Nil

Quick setup: console handler with specified level

Example:

log.configure_console(log.debug_level)

configure_full

</> 
pub fn configure_full(
  console_level: level.Level,
  json_path: String,
  json_level: level.Level,
) -> Nil

Quick setup: console + JSON file

Example:

log.configure_full(log.debug_level, "app.jsonl", log.info_level)

configure_json

</> 
pub fn configure_json(path: String, lvl: level.Level) -> Nil

Quick setup: JSON file handler with specified level

Example:

log.configure_json("app.jsonl", log.info_level)

critical

</> 
pub fn critical(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at critical level

critical_lazy

</> 
pub fn critical_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy critical

critical_level

</> 
pub const critical_level: level.Level

Critical level

debug

</> 
pub fn debug(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at debug level

debug_lazy

</> 
pub fn debug_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy debug - most common use case for lazy logging

Example:

// String only constructed if debug level is enabled
log.debug_lazy(fn() { "Item: " <> int.to_string(i) }, [])

debug_level

</> 
pub const debug_level: level.Level

Debug level

emergency

</> 
pub fn emergency(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at emergency level

emergency_lazy

</> 
pub fn emergency_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy emergency

emergency_level

</> 
pub const emergency_level: level.Level

Emergency level (system is unusable)

error

</> 
pub fn error(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at error level

error_lazy

</> 
pub fn error_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy error

error_level

</> 
pub const error_level: level.Level

Error level

handlers

</> 
pub fn handlers() -> List(handler.Handler)

Get current handlers

info

</> 
pub fn info(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at info level

info_lazy

</> 
pub fn info_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy info

info_level

</> 
pub const info_level: level.Level

Info level

log

</> 
pub fn log(
  lvl: level.Level,
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log with explicit level

log_from

</> 
pub fn log_from(
  source: String,
  lvl: level.Level,
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log with source module

log_lazy

</> 
pub fn log_lazy(
  lvl: level.Level,
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy log - only evaluates message function if log will be emitted

Example:

log.debug_lazy(fn() { "Processing " <> expensive_to_string(data) }, [])

log_lazy_all

</> 
pub fn log_lazy_all(
  lvl: level.Level,
  message_fn: fn() -> String,
  fields_fn: fn() -> List(#(String, String)),
) -> Nil

Lazy log with lazy fields - both message and fields evaluated only if needed

notice

</> 
pub fn notice(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at notice level

notice_lazy

</> 
pub fn notice_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy notice

notice_level

</> 
pub const notice_level: level.Level

Notice level (normal but significant)

sampled

</> 
pub fn sampled(
  lvl: level.Level,
  rate: Float,
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log with sampling (only log rate% of messages)

trace

</> 
pub fn trace(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at trace level

trace_lazy

</> 
pub fn trace_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy trace - for high-frequency logs that should be cheap when disabled

trace_level

</> 
pub const trace_level: level.Level

Trace level (fine-grained)

warning

</> 
pub fn warning(
  message: String,
  fields: List(#(String, String)),
) -> Nil

Log at warning level

warning_lazy

</> 
pub fn warning_lazy(
  message_fn: fn() -> String,
  fields: List(#(String, String)),
) -> Nil

Lazy warning

warning_level

</> 
pub const warning_level: level.Level

Warning level

with_context

</> 
pub fn with_context(
  context: List(#(String, String)),
  f: fn() -> a,
) -> a

Execute function with additional context

would_log

</> 
pub fn would_log(lvl: level.Level) -> Bool

Check if any handler would log at this level Use this to avoid expensive computations when log won’t be emitted

✨ Search Document