HewDocumentation 0.9.3

Module std.log

Structured logging with level filters and text or JSON output.

Choose between two entry points:

  1. Module-level functions use the global level and format settings.

  2. Logger values carry their own level and format, so multiple loggers can coexist with different settings without touching the global state.

Usage — module-level

import std.log;

fn main() {
    log.setup();   // set global level to INFO
    log.info("server starting");
    log.info_with("listening", [log.field_int("port", 8080), log.field("env", "prod")]);
    log.debug_with("cache miss", [log.field("key", "user:1")]);
}

Usage — Logger value

import std.log;

fn main() {
    let lg = log.new_logger(log.DEBUG, log.JSON);
    log.logger_info(lg, "startup", [log.field("svc", "auth")]);
    log.logger_debug(lg, "trace", [log.field_int("uid", 42)]);
}

Structured fields

Fields are key=value strings built by the helper functions:

  • log.field(key, val) string value
  • log.field_int(key, n) i64 value
  • log.field_float(key, f) f64 value
  • log.field_bool(key, b) bool value

Pass them as a Vec<string> to any *_with or logger_* function. Empty Vec is valid and equivalent to calling the plain one-arg variant.

Level constants

ERROR (0) > WARN (1) > INFO (2) > DEBUG (3) > TRACE (4)

Output formats

TEXT (0) — coloured timestamp + level + message + fields to stderr:

12:34:56.789 INFO  server starting  port=8080

JSON (1) — single-line NDJSON to stderr:

{"ts":1234567890.123,"level":"INFO","msg":"server starting","port":"8080"}

Contents

Functions

Function new_logger

pub fn new_logger(level: i64, format: i64) -> Logger

Construct a Logger with the given level threshold and output format.

level — minimum severity to emit (0=ERROR … 4=TRACE). format — log.TEXT (0) or log.JSON (1).

Function logger_level

pub fn logger_level(lg: Logger) -> i64

Return the level threshold of a Logger.

Use this accessor to inspect the logger's level filter.

Function logger_format

pub fn logger_format(lg: Logger) -> i64

Return the output format of a Logger.

Returns the logger's configured format constant.

Function field

pub fn field(key: string, val: string) -> string

Build a key=value field from two strings.

Values that contain spaces, double-quotes, backslashes, or newlines are automatically quoted so they roundtrip correctly through the log wire format. field("user", "John Doe") produces user="John Doe" on the wire and renders as user=John Doe in TEXT output.

Example

import std.log;

fn main() {
    let f = log.field("env", "production");    // "env=production"
    let g = log.field("user", "John Doe");     // user="John Doe"  (quoted)
}

Function field_int

pub fn field_int(key: string, val: i64) -> string

Build a key=N field from a string key and an i64 value.

Example

import std.log;

fn main() {
    let f = log.field_int("port", 8080);  // "port=8080"
}

Function field_float

pub fn field_float(key: string, val: f64) -> string

Build a key=X field from a string key and an f64 value.

Example

import std.log;

fn main() {
    let f = log.field_float("ratio", 0.75);  // "ratio=0.75"
}

Function field_bool

pub fn field_bool(key: string, val: bool) -> string

Build a key=true or key=false field.

Example

import std.log;

fn main() {
    let f = log.field_bool("debug", true);  // "debug=true"
}

Function setup

pub fn setup()

Initialize logging at the default INFO level.

Function set_level

pub fn set_level(level: i64)

Set the log level filter.

Levels: 0=error, 1=warn, 2=info, 3=debug, 4=trace.

Examples

import std.log;

fn main() {
    log.set_level(log.DEBUG);
}

Function get_level

pub fn get_level() -> i64

Get the current log level filter.

Function set_format

pub fn set_format(format: i64)

Set the log output format.

Use log.TEXT (0) for coloured text or log.JSON (1) for NDJSON.

Examples

import std.log;

fn main() {
    log.set_format(log.JSON);
    log.info_with("structured", [log.field("service", "api")]);
}

Function get_format

pub fn get_format() -> i64

Get the current log output format.

Function error

pub fn error(msg: string)

Log a message at error level with no structured fields.

Function error_with

pub fn error_with(msg: string, fields: Vec<string>)

Log a message at error level with structured key-value fields.

Example

import std.log;

fn main() {
    log.error_with("request failed", [log.field_int("status", 500), log.field("path", "/api")]);
}

Function warn

pub fn warn(msg: string)

Log a message at warn level with no structured fields.

Function warn_with

pub fn warn_with(msg: string, fields: Vec<string>)

Log a message at warn level with structured key-value fields.

Function info

pub fn info(msg: string)

Log a message at info level with no structured fields.

Function info_with

pub fn info_with(msg: string, fields: Vec<string>)

Log a message at info level with structured key-value fields.

Example

import std.log;

fn main() {
    log.info_with("server started", [log.field_int("port", 8080)]);
}

Function debug

pub fn debug(msg: string)

Log a message at debug level with no structured fields.

Function debug_with

pub fn debug_with(msg: string, fields: Vec<string>)

Log a message at debug level with structured key-value fields.

Function trace

pub fn trace(msg: string)

Log a message at trace level with no structured fields.

Function trace_with

pub fn trace_with(msg: string, fields: Vec<string>)

Log a message at trace level with structured key-value fields.

Function logger_error

pub fn logger_error(lg: Logger, msg: string, fields: Vec<string>)

Emit an error-level message through a Logger with structured fields.

Function logger_warn

pub fn logger_warn(lg: Logger, msg: string, fields: Vec<string>)

Emit a warn-level message through a Logger with structured fields.

Function logger_info

pub fn logger_info(lg: Logger, msg: string, fields: Vec<string>)

Emit an info-level message through a Logger with structured fields.

Example

import std.log;

fn main() {
    let lg = log.new_logger(log.INFO, log.JSON);
    log.logger_info(lg, "ready", [log.field("svc", "auth")]);
}

Function logger_debug

pub fn logger_debug(lg: Logger, msg: string, fields: Vec<string>)

Emit a debug-level message through a Logger with structured fields.

Function logger_trace

pub fn logger_trace(lg: Logger, msg: string, fields: Vec<string>)

Emit a trace-level message through a Logger with structured fields.

Types

Struct Logger

A logger value with its own level filter and output format.

Construct with log.new_logger(level, format). Pass to logger_* functions; it is a plain record so it can be stored in actor fields, passed to functions, or kept in a let binding.

Example

import std.log;

fn main() {
    let lg = log.new_logger(log.DEBUG, log.JSON);
    log.logger_info(lg, "ready", [log.field_int("port", 8080)]);
}

Fields

level: i64
format: i64

Constants

Constant ERROR

pub const ERROR: i64 = 0

Error-level severity (highest priority).

Constant WARN

pub const WARN: i64 = 1

Warning-level severity.

Constant INFO

pub const INFO: i64 = 2

Info-level severity (default threshold after setup()).

Constant DEBUG

pub const DEBUG: i64 = 3

Debug-level severity.

Constant TRACE

pub const TRACE: i64 = 4

Trace-level severity (lowest priority).

Constant TEXT

pub const TEXT: i64 = 0

Coloured text output format (default).

Constant JSON

pub const JSON: i64 = 1

Single-line JSON (NDJSON) output format.