viva_telemetry - v1.0.101

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() {
  log.configure_erlang(log.info_level)
  log.info("Server started", [#("port", "8080")])

  let logger =
    log.logger("app.http")
    |> log.with_field("request_id", "abc123")

  logger
  |> log.logger_info_with("Request completed", [#("status", "200")])
}

Types

Logger

opaque </>

A named immutable logger with persistent structured fields.

This gives applications a small fluent API while keeping the low-level logging functions available for one-off messages.

pub opaque type Logger

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 handlers for the current process.

Logger configuration and context are process-local. Child or worker processes should configure logging themselves or use Erlang :logger forwarding through configure_erlang.

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_erlang

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

Quick setup: forward structured logs to Erlang’s built-in :logger

This is the recommended production integration when running on the BEAM.

configure_erlang_with_name

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

Quick setup: forward structured logs to Erlang’s built-in :logger with a custom logger name attached as metadata.

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

logger

</> 
pub fn logger(source: String) -> Logger

Create a named logger.

logger_alert

</> 
pub fn logger_alert(logger: Logger, message: String) -> Logger

Log an alert message with a named logger.

logger_alert_with

</> 
pub fn logger_alert_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log an alert message with additional one-off fields.

logger_critical

</> 
pub fn logger_critical(logger: Logger, message: String) -> Logger

Log a critical message with a named logger.

logger_critical_with

</> 
pub fn logger_critical_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log a critical message with additional one-off fields.

logger_debug

</> 
pub fn logger_debug(logger: Logger, message: String) -> Logger

Log a debug message with a named logger.

logger_debug_with

</> 
pub fn logger_debug_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log a debug message with additional one-off fields.

logger_emergency

</> 
pub fn logger_emergency(
  logger: Logger,
  message: String,
) -> Logger

Log an emergency message with a named logger.

logger_emergency_with

</> 
pub fn logger_emergency_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log an emergency message with additional one-off fields.

logger_error

</> 
pub fn logger_error(logger: Logger, message: String) -> Logger

Log an error message with a named logger.

logger_error_with

</> 
pub fn logger_error_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log an error message with additional one-off fields.

logger_info

</> 
pub fn logger_info(logger: Logger, message: String) -> Logger

Log an info message with a named logger.

logger_info_with

</> 
pub fn logger_info_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log an info message with additional one-off fields.

logger_log

</> 
pub fn logger_log(
  logger: Logger,
  lvl: level.Level,
  message: String,
) -> Logger

Log with any level using a named logger.

logger_log_with

</> 
pub fn logger_log_with(
  logger: Logger,
  lvl: level.Level,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log with any level and one-off fields using a named logger.

logger_notice

</> 
pub fn logger_notice(logger: Logger, message: String) -> Logger

Log a notice message with a named logger.

logger_notice_with

</> 
pub fn logger_notice_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log a notice message with additional one-off fields.

logger_trace

</> 
pub fn logger_trace(logger: Logger, message: String) -> Logger

Log a trace message with a named logger.

logger_trace_with

</> 
pub fn logger_trace_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log a trace message with additional one-off fields.

logger_warning

</> 
pub fn logger_warning(logger: Logger, message: String) -> Logger

Log a warning message with a named logger.

logger_warning_with

</> 
pub fn logger_warning_with(
  logger: Logger,
  message: String,
  fields: List(#(String, String)),
) -> Logger

Log a warning message with additional one-off fields.

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_bool

</> 
pub fn with_bool(
  logger: Logger,
  key: String,
  value: Bool,
) -> Logger

Add a bool field to a named logger.

with_context

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

Execute function with additional context

with_error

</> 
pub fn with_error(logger: Logger, error: String) -> Logger

Add an error field to a named logger.

with_field

</> 
pub fn with_field(
  logger: Logger,
  key: String,
  value: String,
) -> Logger

Add a string field to a named logger.

with_fields

</> 
pub fn with_fields(
  logger: Logger,
  fields: List(#(String, String)),
) -> Logger

Add many fields to a named logger.

with_float

</> 
pub fn with_float(
  logger: Logger,
  key: String,
  value: Float,
) -> Logger

Add a float field to a named logger.

with_int

</> 
pub fn with_int(
  logger: Logger,
  key: String,
  value: Int,
) -> Logger

Add an integer field to a named logger.

with_option

</> 
pub fn with_option(
  logger: Logger,
  key: String,
  value: option.Option(a),
  encode: fn(a) -> String,
) -> Logger

Add a field only when the option contains a value.

with_result

</> 
pub fn with_result(
  logger: Logger,
  key: String,
  result: Result(a, b),
  encode_ok: fn(a) -> String,
  encode_error: fn(b) -> String,
) -> Logger

Add a result to a named logger.

Successful values are stored under key; errors are stored under the standard error field.

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