Introduction
Logging is one of the most critical yet underestimated parts of any software system. As applications scale, logs evolve from simple print statements into structured telemetry that powers debugging, monitoring, auditing, and incident response.
Today, I’m excited to officially introduce Logly.zig, a production‑grade structured logging library for Zig, built to bring modern observability features — without sacrificing performance or developer ergonomics.
Logly.zig is designed for applications that care about performance, correctness, and clarity, from small CLIs to high‑throughput backend systems and even bare‑metal environments.
Why Another Logging Library?
Zig’s standard library (std.log) is intentionally minimal. While it offers excellent raw performance, it leaves most real‑world requirements to the developer:
As projects grow, developers repeatedly re‑implement the same logging infrastructure. Logly.zig exists to solve this once, properly, and efficiently.
What Is Logly.zig?
Logly.zig is a high‑performance structured logging framework designed specifically for Zig 0.15+. It provides:
A clean, intuitive API (logger.info(), logger.err(), etc.)
Structured JSON logging out of the box
Multiple sinks (console, file, network)
Async, thread‑safe logging with minimal overhead
Enterprise‑grade features like redaction, metrics, tracing, and diagnostics
All of this is implemented with Zig’s philosophy in mind: explicitness, performance, and zero‑cost abstractions.
Core Design Principles
1. Developer Experience First
Logly.zig adopts a Python‑inspired API while remaining fully Zig‑idiomatic. The goal is to make logging obvious and pleasant rather than verbose or error‑prone.
2. Zero‑Cost Abstractions
Features you don’t enable incur no runtime cost. Whether you’re logging a single message or millions per second, Logly adapts to your needs.
3. Production‑Grade by Default
Rotation, retention, redaction, metrics, async I/O, and diagnostics are not afterthoughts — they are first‑class citizens.
Logly works on Linux, macOS, Windows, and freestanding/bare‑metal targets with the same API.
Feature Highlights
🔥 Rich Log Levels (10 Levels)
From ultra‑verbose tracing to fatal system crashes:
TRACE → DEBUG → INFO → NOTICE → SUCCESS → WARNING → ERROR → FAIL → CRITICAL → FATAL
Custom levels with custom priorities and colors are fully supported.
🎨 Whole‑Line ANSI Coloring
Unlike most loggers that color only the level label, Logly colors the entire log line, making logs far easier to scan during debugging sessions.
📦 Structured JSON Logging
Switch to JSON output with a single config flag:
{"timestamp":1701234567890,"level":"INFO","message":"Application started"}
Perfect for ingestion into systems like ELK, Loki, Datadog, or custom pipelines.
📁 File Logging with Rotation & Retention
Time‑based rotation (minutely → yearly)
Size‑based rotation
Retention policies
Optional compression (gzip, zlib, zstd)
All handled automatically.
⚡ Async & High‑Throughput Logging
Logly includes an async logger with ring buffers, background workers, and thread pools.
In high‑throughput mode, Logly reaches 36+ million log events per second.
🔐 Redaction & Security
Sensitive data can be automatically masked:
Passwords
API keys
Tokens
Custom patterns
This makes Logly safe for GDPR‑compliant and security‑sensitive environments.
📊 Metrics & Observability
Logly tracks:
Log counts by level
Error rates
Drop rates
Throughput
Uptime
Metrics are accessible programmatically for monitoring systems.
🔗 Distributed Tracing
Built‑in support for:
Trace IDs
Span IDs
Correlation IDs
This allows Logly to integrate cleanly with distributed systems and microservices.
🩺 System Diagnostics
Emit system‑level diagnostics automatically:
OS information
CPU details
Memory usage
Drive statistics
Ideal for startup logs or crash analysis.
🧠 Rules System (Unique Feature)
Logly introduces a compiler‑style rules system that can attach guided diagnostics to log messages:
Causes
Fixes
Documentation links
This feature is not available in std.log, nexlog, or log.zig.
Installation
The recommended way is using Zig’s package manager:
zig fetch --save https://github.com/muhammad-fiaz/logly.zig/archive/refs/tags/0.1.0.tar.gz
Logly also ships prebuilt static libraries for Windows, Linux, macOS, and bare‑metal targets.
Quick Example
const std = @import("std");
const logly = @import("logly");
pub fn main() !void {
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const logger = try logly.Logger.init(gpa.allocator());
defer logger.deinit();
try logger.info("Application started", @src());
try logger.success("Initialization complete", @src());
}
📊 LOGLY.ZIG BENCHMARK RESULTS
\> These benchmark based on logly v0.1.0
### 🧪 Environment Details
| Parameter | Value |
| ----------------------- | -------------- |
| Platform | Linux |
| Architecture | x86_64 |
| Warmup Iterations | 100 |
| Benchmark Iterations | 10,000 |
| Multi-thread Iterations | 5,000 / thread |
---
## 🔹 Basic Logging
| Benchmark | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| -------------------------- | --------: | -----------------: | ----------------------- |
| Simple log (no color) | 573,272 | 1,744 | Plain text output |
| Formatted log (no color) | 20,165 | 49,591 | Printf-style formatting |
| Simple log (with color) | 723,660 | 1,382 | ANSI color codes |
| Formatted log (with color) | 19,206 | 52,066 | Colored + formatting |
---
## 🔹 JSON Logging
| Benchmark | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| --------------- | --------: | -----------------: | --------------------- |
| JSON compact | 443,300 | 2,256 | Compact JSON output |
| JSON formatted | 19,913 | 50,218 | JSON with formatting |
| JSON pretty | 358,435 | 2,790 | Indented JSON output |
| JSON with color | 444,222 | 2,251 | JSON with ANSI colors |
---
## 🔹 Log Levels
| Level | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| -------- | --------: | -----------------: | ------------------- |
| TRACE | 685,372 | 1,459 | Lowest priority |
| DEBUG | 668,790 | 1,495 | Debug information |
| INFO | 881,073 | 1,135 | General information |
| SUCCESS | 626,202 | 1,597 | Success messages |
| WARNING | 788,503 | 1,268 | Warning messages |
| ERROR | 852,147 | 1,174 | Error messages |
| FAIL | 794,509 | 1,259 | Failure messages |
| CRITICAL | 565,150 | 1,769 | Critical messages |
---
## 🔹 Custom Features
| Feature | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes | | |
| -------------------- | --------: | -----------------: | --------------------- | ------- | ---------- |
| Custom level (AUDIT) | 603,261 | 1,658 | User-defined level | | |
| Custom log format | 530,158 | 1,886 | `{time} | {level} | {message}` |
| Custom time format | 489,410 | 2,043 | DD/MM/YYYY HH:mm:ss | | |
| ISO 8601 time | 921,460 | 1,085 | ISO standard | | |
| Unix timestamp (ms) | 1,365,288 | 732 | Millisecond precision | | |
---
## 🔹 Configuration Presets
| Preset | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ------------------ | ---------: | -----------------: | --------------------------- |
| Full metadata | 876,521 | 1,141 | Time + module + file + line |
| Minimal config | 2,096,635 | 477 | Minimal metadata |
| Production | 702,837 | 1,423 | JSON + sampling + metrics |
| Development | 671,706 | 1,489 | Debug + source location |
| High throughput | 17,039,984 | 59 | Async + thread pool |
| Secure preset | 533,106 | 1,876 | Redaction enabled |
| Multiple sinks (3) | 375,208 | 2,665 | Text + JSON + Pretty |
---
## 🔹 Allocator Comparison
| Allocator | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ----------------- | --------: | -----------------: | --------------------- |
| GPA | 476,751 | 2,098 | Default allocator |
| GPA (formatted) | 20,141 | 49,650 | Formatting overhead |
| Arena | 358,245 | 2,791 | Reduced alloc cost |
| Arena (formatted) | 16,014 | 62,444 | Arena + formatting |
| Page allocator | 526,255 | 1,900 | System page allocator |
---
## 🔹 Enterprise Features
| Feature | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ------------------ | --------: | -----------------: | ---------------------- |
| Context (3 fields) | 45,521 | 21,968 | Context binding |
| Trace context | 588,085 | 1,700 | Trace + span IDs |
| Metrics enabled | 666,317 | 1,501 | Metrics collection |
| Structured logging | 481,134 | 2,078 | JSON structured output |
---
## 🔹 Sampling & Rate Limiting
| Mode | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ----------------------- | --------: | -----------------: | ----------- |
| Sampling (50%) | 655,222 | 1,526 | Probability |
| Sampling (rate) | 605,324 | 1,652 | Rate-based |
| Sampling (adaptive) | 518,268 | 1,930 | Adaptive |
| Sampling (every-N) | 717,864 | 1,393 | Every-N |
| Rate limiting (10K/sec) | 685,247 | 1,459 | Hard limit |
| With redaction | 680,043 | 1,470 | PII masking |
---
## 🔹 Filtering
| Filter Mode | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ----------- | ---------: | -----------------: | --------------- |
| Allowed | 675,019 | 1,481 | Message allowed |
| Rejected | 17,104,806 | 58 | Message dropped |
---
## 🔹 Rules Engine
| Mode | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| -------------- | --------: | -----------------: | --------------- |
| Rules enabled | 662,503 | 1,509 | Rule evaluation |
| Rules disabled | 495,316 | 2,019 | No rules |
---
## 🔹 Redaction
| Mode | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| --------------- | --------: | -----------------: | ------------------ |
| Pattern match | 12,128 | 82,453 | Regex match |
| No match | 12,347 | 80,994 | No regex hit |
| Field redaction | 280,702 | 3,563 | Full field masking |
---
## 🔹 Metrics
| Operation | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ----------------- | ---------: | -----------------: | ---------------- |
| recordLog | 9,952,190 | 100 | Atomic counter |
| Metrics + latency | 5,621,458 | 178 | Latency tracking |
| Snapshot | 12,239,093 | 82 | Metrics snapshot |
| Full metrics | 9,401,014 | 106 | All enabled |
---
## 🔹 Rotation
| Benchmark | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| --------------------- | --------: | -----------------: | ---------- |
| Rotation (size check) | 427,016 | 2,342 | Size-based |
---
## 🔹 System Diagnostics
| Benchmark | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ------------------ | --------: | -----------------: | ---------- |
| System diagnostics | 30,133 | 33,186 | OS/CPU/Mem |
---
## 🔹 Multi-Threading
| Scenario | Ops/sec ↑ | Avg Latency (ns) ↓ | Notes |
| ------------------- | --------: | -----------------: | ----------- |
| Single thread | 720,410 | 1,388 | Baseline |
| 2 threads | 598,362 | 1,671 | Parallel |
| 4 threads | 425,791 | 2,349 | Parallel |
| 8 threads | 447,671 | 2,234 | Parallel |
| 16 threads | 403,202 | 2,480 | Parallel |
| 4 threads JSON | 303,571 | 3,294 | Structured |
| 4 threads colored | 405,199 | 2,468 | ANSI |
| 4 threads formatted | 276,631 | 3,615 | Formatting |
| 4 threads arena | 280,415 | 3,566 | Arena alloc |
---
## 📈 Benchmark Summary
| Metric | Value |
| ------------------ | ------------------ |
| Total benchmarks | 69 |
| Average throughput | 1,525,897 ops/sec |
| Maximum throughput | 17,104,806 ops/sec |
| Minimum throughput | 12,128 ops/sec |
| Average latency | 655 ns |
When Should You Use Logly.zig?
Use Logly if you need:
Stick with std.log if you only need minimal stderr output and zero dependencies.
Final Thoughts
Logly.zig is not just a logger ,it’s an observability foundation for Zig applications.
If you’re building serious software in Zig and want logging that scales with your system, Logly.zig is built for you.
⭐ If you find Logly.zig useful, consider starring the repository and contributing!
Links
