🪵 Buche - the French word for "log".

This is a Zig library for logging by using the Standard Library logging facade.

Buche uses a simple double buffered writer, which is set as comptime with the rest of the configuration. The idea is to minimize the number of allocations; the only place that requires a memory allocation is when the logger is configured to accept environment variables.

I hope you like it.

Features

Logs via the Standard Library logging facade
Filters
- Global filter
- On individual sink
- By using an environment variable
Customizable log headers
- A default is supplied for ease of development
Zero allocations when no filtering with environment variable
Small footprint
Blaz... ok... 🙄

What does it do?

50 threads, 200,000 iterations each thread, 1 error logging, 1 debug logging, with the timestamp (human readable), the log level and the scope:

[2025-05-04T01:32:26.157Z][err][default] An error message
[2025-05-04T01:32:26.157Z][debug][default] 321 ZIG! let's see...

Something to look at:

$ poop ./zig-out/bin/bench

Benchmark 1 (3 runs): ./zig-out/bin/bench
  measurement          mean ± σ            min … max           outliers
  wall_time          6.59s  ± 23.2ms    6.57s  … 6.62s           0 ( 0%)
  peak_rss           345KB ± 82.8KB     250KB …  393KB           0 ( 0%)
  cpu_cycles         67.5G  ±  155M     67.4G  … 67.7G           0 ( 0%)
  instructions       84.5G  ± 13.9M     84.5G  … 84.6G           0 ( 0%)
  cache_references    664M  ± 26.8M      643M  …  694M           0 ( 0%)
  cache_misses        152M  ±  161K      151M  …  152M           0 ( 0%)
  branch_misses      65.6M  ± 1.38M     64.7M  … 67.2M           0 ( 0%)

This gives you a log file like this:

$ ls -l wrk-xyz.log
-rw-r--r-- 1 group user 3690000000 May  3 11:32 wrk-xyz.log

How to use it?

There are examples in the examples folder. Also, there is the full documentation here.

In a nutshell

build.zig

    // -->> Buche module. <<--
    const buche_mod = b.addModule("buche", .{
        .root_source_file = b.path("src/buche.zig"),
        .target = target,
        .optimize = optimize,
    });
 
    // Your module declaration...
    const simple_mod = b.createModule(.{
        .root_source_file = b.path("examples/simple.zig"),
        .target = target,
        .optimize = optimize,
    });

    // -->> Add the "buche" module to your own module. <<--
    simple_mod.addImport("buche", buche_mod);

simple.zig

// Import.
const buche = @import("buche");

// Define your configuration here, or not to use the default...
pub const buche_options = buche.Options{ ... };

// Hook to the standard library logging interface.
pub const std_options = buche.std_hook();

Requirements

Zig 0.14.0
Probably Linux, I only tested on Linux glibc.

README