A production-grade, high-performance structured logging library for Zig, designed with a clean, intuitive, and developer-friendly API.

Installation

Method 1: Zig Fetch (Recommended)

The easiest way to add Logly to your project:

zig fetch --save https://github.com/muhammad-fiaz/logly.zig/archive/refs/tags/v0.0.3.tar.gz

This automatically adds the dependency with the correct hash to your build.zig.zon.

Method 2: Manual Configuration

Add to your build.zig.zon:

.dependencies = .{
    .logly = .{
        .url = "https://github.com/muhammad-fiaz/logly.zig/archive/refs/tags/v0.0.3.tar.gz",
        .hash = "...", // you needed to add hash here :)
    },
},

Note: Run zig fetch --save <url> to automatically get the correct hash, or run zig build and copy the expected hash from the error message.

Then in your build.zig:

const logly = b.dependency("logly", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("logly", logly.module("logly"));

📦 Prebuilt Library

While we recommend using the Zig Package Manager, we also provide prebuilt static libraries for each release on the Releases page. These can be useful for integration with other build systems or languages.

• Windows: logly-x86_64-windows.lib, logly-x86-windows.lib
• Linux: liblogly-x86_64-linux.a, liblogly-x86-linux.a, liblogly-aarch64-linux.a
• macOS: liblogly-x86_64-macos.a, liblogly-aarch64-macos.a
• Bare Metal: liblogly-x86_64-freestanding.a, liblogly-aarch64-freestanding.a, liblogly-riscv64-freestanding.a, liblogly-arm-freestanding.a

To use them, link against the static library in your build process.

Example build.zig:

// Assuming you downloaded the library to `libs/`
exe.addLibraryPath(b.path("libs"));
exe.linkSystemLibrary("logly");

Quick Start

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

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Enable ANSI colors on Windows (no-op on Linux/macOS)
    _ = logly.Terminal.enableAnsiColors();

    // Create logger (console sink auto-enabled)
    const logger = try logly.Logger.init(allocator);
    defer logger.deinit();

    // Log at different levels - entire line is colored!
    try logger.trace("Detailed trace information");   // Cyan
    try logger.debug("Debug information");            // Blue
    try logger.info("Application started");           // White
    try logger.success("Operation completed!");       // Green
    try logger.warning("Warning message");            // Yellow
    try logger.err("Error occurred");                 // Red
    try logger.fail("Operation failed");              // Magenta
    try logger.critical("Critical system error!");    // Bright Red
}

Usage Examples

File Logging

const logger = try logly.Logger.init(allocator);
defer logger.deinit();

// Disable auto console sink
var config = logly.Config.default();
config.auto_sink = false;
logger.configure(config);

// Add file sink
_ = try logger.addSink(.{
    .path = "logs/app.log",
});

try logger.info("Logging to file!");
try logger.flush(); // Ensure data is written

File Rotation

// Daily rotation with 7-day retention
_ = try logger.addSink(.{
    .path = "logs/daily.log",
    .rotation = "daily",
    .retention = 7,
});

// Size-based rotation (10MB limit, keep 5 files)
_ = try logger.addSink(.{
    .path = "logs/app.log",
    .size_limit = 10 * 1024 * 1024,
    .retention = 5,
});

// Combined: rotate daily OR when 5MB reached
_ = try logger.addSink(.{
    .path = "logs/combined.log",
    .rotation = "daily",
    .size_limit = 5 * 1024 * 1024,
    .retention = 10,
});

JSON Logging

var config = logly.Config.default();
config.json = true;
config.pretty_json = true;
logger.configure(config);

try logger.info("JSON formatted log");
// Output: {"timestamp":1701234567890,"level":"INFO","message":"JSON formatted log"}

Context Binding

// Application-wide context
try logger.bind("app", .{ .string = "myapp" });
try logger.bind("version", .{ .string = "1.0.0" });

try logger.info("Application started");
// All logs include app and version fields

// Request-specific context
try logger.bind("request_id", .{ .string = "req-12345" });
try logger.info("Processing request");
logger.unbind("request_id"); // Clean up

Callbacks

fn logCallback(record: *const logly.Record) !void {
    if (record.level.priority() >= logly.Level.err.priority()) {
        // Send alert, update metrics, etc.
        std.debug.print("[ALERT] {s}\n", .{record.message});
    }
}

logger.setLogCallback(&logCallback);
try logger.err("Error occurred"); // Callback triggers

Custom Log Levels

// Add custom level between WARNING (30) and ERROR (40)
try logger.addCustomLevel("NOTICE", 35, "96"); // Cyan color
try logger.addCustomLevel("AUDIT", 25, "35;1"); // Magenta Bold

// Use custom levels - supports all features like standard levels
try logger.custom("NOTICE", "Custom level message");
try logger.custom("AUDIT", "User action recorded");

// Formatted custom level messages
try logger.customf("AUDIT", "User {s} logged in from {s}", .{ "alice", "10.0.0.1" });

// Custom levels work with JSON output
var config = logly.Config.default();
config.json = true;
logger.configure(config);
try logger.custom("AUDIT", "Appears as level: AUDIT in JSON");

// Custom levels work with file sinks
_ = try logger.addSink(.{ .path = "logs/audit.log" });
try logger.custom("AUDIT", "Written to file with custom level name");

Multiple Sinks

// Console
_ = try logger.addSink(.{});

// Application logs
_ = try logger.addSink(.{
    .path = "logs/app.log",
    .rotation = "daily",
    .retention = 7,
});

// Error-only file
_ = try logger.addSink(.{
    .path = "logs/errors.log",
    .level = .err, // Only ERROR and above
});

Distributed Tracing

// Set trace context for request tracking
try logger.setTraceContext("trace-abc123", "span-001");
try logger.setCorrelationId("request-789");

try logger.info("Processing request");

// Create child spans for nested operations
{
    var span = try logger.startSpan("database-query");
    try logger.info("Executing query");
    try span.end(null);
}

// Clear context
logger.clearTraceContext();

Filtering

var filter = logly.Filter.init(allocator);
defer filter.deinit();

// Only allow warnings and above
try filter.addMinLevel(.warning);

logger.setFilter(&filter);

Sampling

// Sample 50% of logs for high-throughput scenarios
var sampler = logly.Sampler.init(allocator, .{ .probability = 0.5 });
defer sampler.deinit();

logger.setSampler(&sampler);

Redaction

var redactor = logly.Redactor.init(allocator);
defer redactor.deinit();

// Mask passwords in logs
try redactor.addPattern(
    "password",
    .contains,
    "password=",
    "[REDACTED]",
);

logger.setRedactor(&redactor);
try logger.info("User login: password=secret123");
// Output: "User login: [REDACTED]secret123"

Metrics

const logger = try logly.Logger.init(allocator);
defer logger.deinit();

// Enable metrics collection
logger.enableMetrics();

// Log some messages
try logger.info("Request processed");
try logger.err("Database error");

// Get metrics snapshot
if (logger.getMetrics()) |snapshot| {
    std.debug.print("Total logs: {}\n", .{snapshot.total_records});
    std.debug.print("Errors: {}\n", .{snapshot.error_count});
}

Production Configuration

// Use preset configurations
const config = logly.ConfigPresets.production();
logger.configure(config);

// Or customize
var config = logly.Config.production();
config.level = .info;
config.include_hostname = true;
logger.configure(config);

Configuration

var config = logly.Config.default();

// Global controls
config.global_color_display = true;
config.global_console_display = true;
config.global_file_storage = true;

// Log level
config.level = .debug;

// Display options
config.show_time = true;
config.show_module = true;
config.show_function = false;
config.show_filename = false;
config.show_lineno = false;

// Output format
config.json = false;
config.color = true;

// Features
config.enable_callbacks = true;
config.enable_exception_handling = true;

logger.configure(config);

Module Configuration

Configure advanced features like async logging, compression, thread pools, and scheduling:

var config = logly.Config.default();

// Async logging for non-blocking writes
config.async_config = .{
    .enabled = true,
    .buffer_size = 8192,
    .batch_size = 100,
    .flush_interval_ms = 100,
    .overflow_policy = .drop_oldest,
    .auto_start = true,
};

// Compression for log files
config.compression = .{
    .enabled = true,
    .algorithm = .deflate,
    .level = .default,
    .on_rotation = true,
    .keep_original = false,
    .extension = ".gz",
};

// Thread pool for parallel processing
config.thread_pool = .{
    .enabled = true,
    .thread_count = 4,       // 0 = auto-detect CPU cores
    .queue_size = 10000,
    .stack_size = 1024 * 1024,
    .work_stealing = true,
};

// Scheduler for automatic maintenance
config.scheduler = .{
    .enabled = true,
    .cleanup_max_age_days = 7,
    .max_files = 10,
    .compress_before_cleanup = true,
    .file_pattern = "*.log",
};

logger.configure(config);

Or use convenient helper methods:

var config = logly.Config.default()
    .withAsync()
    .withCompression()
    .withThreadPool(4)
    .withScheduler();

Log Levels

Rotation Intervals

• minutely - Rotate every minute
• hourly - Rotate every hour
• daily - Rotate every day
• weekly - Rotate every week
• monthly - Rotate every 30 days
• yearly - Rotate every 365 days

Performance & Benchmarks

Logly.Zig is designed for high-performance logging with minimal overhead. Below are benchmark results from running zig build bench:

Benchmark Results

Average Throughput: ~17,000 ops/sec

Note: Benchmark results may vary based on operating system, environment, Zig version, hardware specifications, and software configurations.

Reproducing the Benchmark Results

To reproduce the benchmark table above locally, run the benchmark executable included with the repository. The benchmark implementation is at bench/benchmark.zig and is licensed under the repository's LICENSE (MIT) in the project root.

Run the benchmark with the following command (Windows and POSIX both supported):

# Build and run the benchmark (default build output in `zig-out`)
zig build bench

# Or build then run the built executable directly (useful if you pass extra flags to build):
zig build -p zig-out
./zig-out/bin/benchmark       # POSIX
.\zig-out\bin\benchmark.exe # Windows PowerShell

Notes:

• The benchmark code uses a null output path (NUL on Windows, /dev/null on POSIX) during tests so console/file I/O does not bottleneck results; you can inspect bench/benchmark.zig for details and tune BENCHMARK_ITERATIONS/WARMUP_ITERATIONS to extend runs.
• The printed results include the benchmark name, operations per second, average latency (ns), and a short notes column indicating the operation. Results will vary by OS, Zig version, hardware, and environment.

Performance Notes

• JSON logging is fastest due to simpler string concatenation
• Color overhead is minimal (~2-3% performance impact)
• Formatted logging (infof, debugf, etc.) adds ~10% overhead vs simple strings
• Full metadata (file, line, function) adds ~15% overhead
• All benchmarks use ReleaseFast optimization
• Results measured on Windows with output to NUL device

Building

# Run tests
zig build test

# Build examples
zig build example-basic
zig build example-file_logging
zig build example-rotation
zig build example-json_logging
zig build example-callbacks
zig build example-context
zig build example-advanced_config
zig build example-module_levels
zig build example-sink_formats
zig build example-formatted_logging

# Enterprise feature examples
zig build example-filtering
zig build example-sampling
zig build example-redaction
zig build example-metrics
zig build example-tracing
zig build example-color_options
zig build example-production_config

# Advanced feature examples
zig build example-compression
zig build example-thread_pool
zig build example-scheduler
zig build example-async_advanced

# Run an example
./zig-out/bin/basic

Documentation

Full documentation is available at: https://muhammad-fiaz.github.io/logly.zig

Comparison with Logly Other Variants

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Links

• Documentation: https://muhammad-fiaz.github.io/logly.zig
• Repository: https://github.com/muhammad-fiaz/logly.zig
• Issues: https://github.com/muhammad-fiaz/logly.zig/issues
• Rust Version: https://github.com/muhammad-fiaz/logly-rs
• Python Version: https://github.com/muhammad-fiaz/logly