zlog

Standard Library log wrapper. zlog provides adjusted std.log output and a pretty print function for easy overwriting of user defined types (struct, enum, union and vector).

Usage

The following snippet shows an example usage of zlog to change the default log format and add pretty printing to both user defined types (Options and Struct):

const std = @import("std");
const zlog = @import("zlog");

// use this to overwrite the default log format of `std.log`
pub const std_options = zlog.std_options;

const Options = enum {
    a,
    b,
    c,

    // copy and paste this function into your user defined types to enable pretty printing for these types
    pub fn format(value: @This(), comptime fmt: []const u8, options: std.fmt.FormatOptions, writer: anytype) anyerror!void {
        try zlog.pretty_format(value, fmt, options, writer);
    }
};

const Struct = struct {
    a: usize = 42,
    b: bool = true,
    c: [5]u16 = .{ 1, 2, 3, 4, 5 },
    d: []const u8 = "string",
    e: Options = Options.b,

    // same function as above...
    pub fn format(value: @This(), comptime fmt: []const u8, options: std.fmt.FormatOptions, writer: anytype) anyerror!void {
        try zlog.pretty_format(value, fmt, options, writer);
    }
};

pub fn main() void {
    // initialize zlog with the scope of `main`
    const log = std.log.scoped(.main);
    // NOTE: the scope of `default` will result in no scoping being printed in
    // the resulting output (default behavior of `std.log.defaultLog`)

    // some variables to log
    const int_var = 42;
    const array_var = [_]i32{ 1, 2, 3, 4 };
    const string_var = "This is a test";
    const option_var = Options.a;
    const struct_var: Struct = .{};

    // NOTE: Depending on the optimization target some of these log messages
    // will not show, which is inline with the behavior of `std.log`.
    log.debug("Debug message {any}", .{int_var});
    log.info("Info message {any}", .{array_var});
    log.info("Info message \"{s}\"", .{string_var});
    log.warn("Warning message {any}", .{option_var});
    log.err("Error message {any}", .{struct_var});
}

This will result in the following output:

[2024-08-28 22:22] debug(main): Debug message 42
[2024-08-28 22:22] info(main): Info message { 1, 2, 3, 4 }
[2024-08-28 22:22] info(main): Info message "This is a test"
[2024-08-28 22:22] warning(main): Warning message main.Options = enum {
        a,
        b,
        c,
} = a
[2024-08-28 22:22] error(main): Error message main.Struct = struct {
        .a = 42,
        .b = true,
        .c = []u16: { 1, 2, 3, 4, 5 },
        .d = { 115, 116, 114, 105, 110, 103 },
        .e = main.Options = enum {
                a,
                b,
                c,
        } = b,
}

Customization

For more details about the output customization see the configuration options of the zlog module. Following options are available:

• timestamp (default: true): Prepend the current timestamp before each log message.
• stderr (default: true): Print log messages to stderr. NOTE: Currently not working as log output is not appended and only the last log message will be in the resulting log file! This is a not-yet-implemented feature of the standard library of zig! See this issue for more details.

Tips

The following list shows some tips on how to use logging more effectively. These tips do not apply just to zlog (and not even only to zig code).

• Use errdefer to directly print messages on failures in the same function they occur:

  // assume log is already defined before (with the corresponding scope)
  const port = port: {
    errdefer |err| log.err("failed to read the port number: {}", .{err});
  
    var buf: [fmt.count("{}\n", .{maxInt(u16)})]u8 = undefined;
    const len = try process.stdout.?.readAll(&buf);
    break :port try fmt.parseInt(u16, buf[0 .. len -| 1], 10);
  };