# Logly.Zig > High-Performance Logging for Zig Production-ready structured logging with a clean, simple API ## Table of Contents ### Introduction - [What is Logly.zig?](/logly.zig/guide/introduction.md): Logly.zig is a high-performance structured logging library for Zig with zero-copy architecture, async I/O, JSON output, file rotation, and enterprise features like redaction, metrics, and distributed tracing. - [Installation Guide](/logly.zig/guide/installation.md): Install Logly.zig in your Zig project using zig fetch, manual configuration, or prebuilt libraries. Supports Windows, Linux, macOS, and bare-metal targets with step-by-step instructions. - [Getting Started with Logly.zig](/logly.zig/guide/getting-started.md): Learn how to install and set up Logly.zig in your Zig project. This beginner-friendly guide covers installation via zon package manager, basic configuration, and your first logging example. - [Quick Start Guide](/logly.zig/guide/quick-start.md): Get started with Logly.zig in minutes. Learn basic console logging, file rotation, JSON output, context binding, and more with practical examples. ### Core Concepts - [Log Levels](/logly.zig/guide/log-levels.md): Explore the 10 built-in log levels in Logly.zig. Learn about priorities, whole-line coloring, custom levels, and fine-grained level filtering for modules. - [Configuration Guide](/logly.zig/guide/configuration.md): Complete guide to configuring Logly.zig. Learn about log levels, output formats, JSON logging, color settings, async configuration, thread pools, compression, and enterprise features like filtering, sampling, and redaction. - [Zero-Downtime Hot-Reload](/logly.zig/guide/hot-reload.md): Learn how to dynamically reload Logly configuration at runtime from JSON files without restarts or dropping logs. - [Colors and Styling](/logly.zig/guide/colors.md): Master ANSI color support in Logly.zig. Learn about whole-line coloring, custom level colors, and enabling colors on Windows, Linux, and macOS. - [Log Sinks Guide](/logly.zig/guide/sinks.md): Configure log sinks in Logly.zig for console, file, network (TCP/UDP), and system event log output. Learn about rotation, compression, async writing, and multi-sink configurations. - [Logging Formats](/logly.zig/guide/formatting.md): Customize your log output with Logly.zig. Learn about default formats, custom themes, JSON formatting, and flexible timestamp placeholders for any scenario. - [MessagePack Binary Formatter](/logly.zig/guide/msgpack.md): Learn how to utilize Logly's compact MessagePack binary formatter to minimize network and disk footprints. - [Custom Log Levels](/logly.zig/guide/custom-levels.md): Define your own log levels with Logly.zig. Customize level names, priorities, and colors to fit your application's domain requirements perfectly. ### Core Features - [File Rotation Guide](/logly.zig/guide/rotation.md) - [JSON Logging](/logly.zig/guide/json.md): Enable structured JSON logging in Logly.zig for modern observability stacks. Configure global or per-sink JSON output with custom levels and pretty-printing. - [Context Binding](/logly.zig/guide/context.md): Use context binding in Logly.zig to attach persistent key-value pairs to logs. Track user sessions, request IDs, and system state effortlessly. - [Logging Callbacks](/logly.zig/guide/callbacks.md): Use callbacks in Logly.zig to hook into the logging process. Monitor events, track metrics, and trigger alerts across the entire logging pipeline. - [Source Location Display](/logly.zig/guide/source-location.md): Enhance logs with source file paths and line numbers in Logly.zig. Learn how to use @src() and custom format strings for effortless debugging. - [Stack Traces](/logly.zig/guide/stack-traces.md): Debug issues faster with automatic stack trace capture in Logly.zig. Pinpoint errors with captured memory addresses and runtime symbolization. ### Advanced Features - [Async Logging Guide](/logly.zig/guide/async.md): Master asynchronous logging in Logly.zig with ring buffers, worker threads, batch processing, and non-blocking I/O. Achieve up to 36M ops/sec throughput without blocking your application. - [Log Compression Guide](/logly.zig/guide/compression.md): Learn how to compress log files with Logly.zig using DEFLATE, GZIP, ZLIB, ZSTD, LZMA, XZ, LZ4, and archive formats. Covers automatic rotation compression, background processing, streaming mode, and performance optimization. - [Memory-Mapped (mmap) Sinks](/logly.zig/guide/mmap.md): Explore Logly's ultra-high-performance memory-mapped file sinks for zero-copy, microsecond-latency disk writes. - [Thread Pool Guide](/logly.zig/guide/thread-pool.md): Learn how to use Logly.zig's high-performance thread pool for parallel log processing. Covers worker configuration, task submission, batch processing, priority queues, work stealing, and cache-aware scheduling. - [Logging Scheduler](/logly.zig/guide/scheduler.md): Automate log maintenance with the Logly.zig scheduler. Schedule cleanup, compression, rotation, and health checks to keep your logs managed and efficient. - [Invoke System Guide](/logly.zig/guide/invoke.md): Learn how to use Logly.zig's Invoke system to attach extra messages to log records when conditions match. - [Compile-Time Configuration](/logly.zig/guide/compile-time.md) - [Network Logging](/logly.zig/guide/network-logging.md): Send logs over TCP and UDP with Logly.zig. Perfect for centralized logging, shipping to collectors like Logstash, and remote application monitoring. ### System & Operations - [Global Crash & Panic Handler](/logly.zig/guide/crash-handler.md): Deep dive into Logly's global panic handler and crash interception mechanism for reliable logging during application failures. ### Enterprise Features - [Log Filtering Guide](/logly.zig/guide/filtering.md): Filter logs by level, module, message pattern, and custom rules in Logly.zig. Learn to create allow/deny rules, batch filtering, and sink-level filters for precise log control. - [Log Sampling Guide](/logly.zig/guide/sampling.md): Control log volume in high-throughput applications with Logly.zig sampling. Use probability sampling, rate limiting, every-Nth message, and adaptive sampling strategies. - [Log Redaction Guide](/logly.zig/guide/redaction.md): Automatically mask sensitive data in logs with Logly.zig. Redact passwords, API keys, credit card numbers, and PII using keyword patterns, regex, and custom rules. - [Logging Metrics Guide](/logly.zig/guide/metrics.md): Monitor logging performance with Logly.zig's built-in metrics. Track record counts, error rates, bytes written, per-level statistics, and sink throughput with atomic counters. - [Distributed Tracing Guide](/logly.zig/guide/tracing.md): Implement distributed tracing with Logly.zig using OpenTelemetry-compatible trace and span IDs. Correlate logs across microservices and track request flows through your system. - [Distributed Systems Guide](/logly.zig/guide/distributed.md): Build distributed logging architectures with Logly.zig. Learn how to propagate context across microservices, configure service identity, and integrate with centralized log aggregators. - [OpenTelemetry Integration](/logly.zig/guide/telemetry.md): Complete guide to OpenTelemetry integration in Logly.zig for distributed tracing, metrics, and observability. - [Cryptographic Tamper-Evident Logs](/logly.zig/guide/tamper-evident.md): Protect your structured log files using Logly's native SHA-256 cryptographic chaining to prevent unauthorized modifications. - [Advanced Customizations](/logly.zig/guide/customizations.md): Tailor Logly.zig to your needs with advanced customizations. Configure global root paths, format structures, per-level colors, and highlighters. - [Allocator Usage](/logly.zig/guide/arena-allocation.md): Learn how to use allocators in Logly.zig for logging. Pass your own allocator to Logger.initWithConfig for full control over memory management. ### API Reference - [Logger API Reference](/logly.zig/api/logger.md): Complete API reference for Logly.zig Logger struct. Covers initialization, log methods, sink management, filtering, sampling, redaction, metrics, and distributed tracing APIs. - [Config API Reference](/logly.zig/api/config.md): API reference for Logly.zig Config struct. Configure log levels, output formats, thread pools, schedulers, compression, async logging, and all enterprise features. - [Distributed Config API Reference](/logly.zig/api/distributed.md): API reference for Logly.zig DistributedConfig struct. Configure service identification, tracing headers, and environment context for microservices. - [Level API Reference](/logly.zig/api/level.md): API reference for Logly.zig Level enum. All 10 built-in log levels (trace, debug, info, success, warning, error, fail, critical, fatal, panic) with priorities and colors. - [addSink Reference](/logly.zig/api/add-sink.md): Complete client-side reference for Logger.addSink and every SinkConfig option in Logly.zig. Target selection, formats, color, buffering, rotation, compression, and memory sinks. - [Sink API Reference](/logly.zig/api/sink.md): API reference for Logly.zig Sink struct. Configure log destinations including console, file, network (TCP/UDP), rotation, compression, and custom outputs. - [Formatter API Reference](/logly.zig/api/formatter.md): API reference for Logly.zig Formatter struct. Custom log formats, JSON output, color themes, and template placeholders for timestamps, levels, and messages. - [Rotation API](/logly.zig/api/rotation.md) - [Invoke API Reference](/logly.zig/api/invoke.md): API reference for Logly.zig Invoke module. Attach extra messages to log records when conditions match — level-based, message content, custom levels, and more. - [Filter API Reference](/logly.zig/api/filter.md): API reference for Logly.zig Filter struct. Create rules to filter logs by level, module, message pattern with allow/deny actions and batch evaluation. - [Sampler API Reference](/logly.zig/api/sampler.md): API reference for Logly.zig Sampler struct. Control log volume with probability sampling, rate limiting, every-Nth, and adaptive sampling strategies. - [Redactor API Reference](/logly.zig/api/redactor.md): API reference for Logly.zig Redactor struct. Mask passwords, API keys, credit cards, and PII with keyword patterns, regex rules, and custom redaction strategies. - [Metrics API Reference](/logly.zig/api/metrics.md): API reference for Logly.zig Metrics struct. Track record counts, bytes written, error rates, per-level statistics, and sink throughput with atomic counters. - [OpenTelemetry API Reference](/logly.zig/api/telemetry.md) - [Network API Reference](/logly.zig/api/network.md): API reference for Logly.zig Network module. TCP, UDP logging, HTTP endpoints, Syslog support, and network compression for centralized log aggregation. - [Record API Reference](/logly.zig/api/record.md): API reference for Logly.zig Record struct. Log event representation with message, level, timestamp, source location, context, trace IDs, and metadata fields. - [Async API Reference](/logly.zig/api/async.md): API reference for Logly.zig AsyncLogger and ring buffer. Non-blocking logging with configurable buffering, batch processing, and up to 36M ops/sec throughput. - [Compression API Reference](/logly.zig/api/compression.md): API reference for Logly.zig Compression module. DEFLATE, GZIP, ZLIB, ZSTD algorithms with streaming support, background processing, and performance monitoring. - [Thread Pool API Reference](/logly.zig/api/thread-pool.md): API reference for Logly.zig ThreadPool module. Covers worker threads, task submission, batch processing, priority queues, work stealing, and parallel sink writing. - [Scheduler API Reference](/logly.zig/api/scheduler.md): API reference for Logly.zig Scheduler module. Automatic log maintenance with scheduled cleanup, compression, rotation, cron expressions, and custom periodic tasks. - [Constants API Reference](/logly.zig/api/constants.md): API reference for Logly.zig Constants. Defines cross-platform atomic types, buffer sizes, and default configuration values. - [Callback API](/logly.zig/api/callbacks.md) - [Customization API Reference](/logly.zig/api/customizations.md): API reference for Logly.zig customization options. Configure logs root path, custom levels, color themes, format templates, and extend logger behavior. - [Utils API Reference](/logly.zig/api/utils.md): API reference for Logly.zig Utils module. Size parsing, duration parsing, time utilities, and date formatting functions. ### Code Examples - [Basic Logging Example](/logly.zig/examples/basic.md): Learn the basics of Logly.zig with this simple example. Covers logger initialization, all 10 built-in log levels, and proper cleanup with defer. - [File Logging Example](/logly.zig/examples/file-logging.md): Example of logging to files with Logly.zig. Write logs to multiple destinations including console and files with automatic directory creation. - [Rotation Examples](/logly.zig/examples/rotation.md) - [JSON Logging Example](/logly.zig/examples/json.md): Example of structured JSON logging with Logly.zig. Output logs in JSON format for ELK, Datadog, CloudWatch with context binding and pretty printing. - [Extended JSON Logging Example](/logly.zig/examples/json-extended.md): Example of extended JSON fields in Logly.zig including hostname, PID, and context binding. Essential for distributed systems and log aggregation. - [Invoke System Example](/logly.zig/examples/invoke.md): Example of the Logly.zig Invoke system. Attach extra messages to log records when conditions match. - [Custom Colors Example](/logly.zig/examples/custom-colors.md): Example of defining custom ANSI colors for log levels in Logly.zig. Create bold, underlined, and reverse color effects for custom log levels. - [Custom Theme Example](/logly.zig/examples/custom-theme.md): Example of creating and applying custom color themes in Logly.zig. Override default ANSI colors for each log level and customize output format templates. - [Color Control Example](/logly.zig/examples/color-control.md): Example of ANSI color control in Logly.zig. Configure global and per-sink colors, custom level colors, Windows support, and color modifiers for terminals. - [Context Binding Example](/logly.zig/examples/context.md): Example of attaching metadata to logs with Logly.zig context binding. Track requests, user sessions, and system state across multiple log messages. - [Log Callbacks Example](/logly.zig/examples/callbacks.md): Example of monitoring log events with callbacks in Logly.zig. Trigger external alerts, metrics, or custom logic when specific log messages are processed. - [Async Logging Example](/logly.zig/examples/async-logging.md): Example of high-performance async logging with Logly.zig. Configure ring buffers, batch processing, and background I/O for non-blocking log operations. - [Network Logging Example](/logly.zig/examples/network-logging.md): Example of sending logs over TCP and UDP with Logly.zig. Configure network sinks with JSON formatting, compression, and centralized log aggregation. - [Advanced Configuration Example](/logly.zig/examples/advanced-config.md): Example of advanced Logly.zig configuration including custom log formats, timestamps, timezone, colors, enterprise features, and multiple sinks with different settings. - [Module Levels Example](/logly.zig/examples/module-levels.md): Example of module-specific log levels in Logly.zig. Control logging verbosity for different parts of your application with scoped loggers and per-module settings. - [Custom Levels Full Example](/logly.zig/examples/custom-levels-full.md): Complete example of custom log levels in Logly.zig with console, file, JSON output, context binding, and formatted messages all working together. - [Sink Formats Example](/logly.zig/examples/sink-formats.md): Example of configuring different output formats per sink in Logly.zig. Plain text console, raw JSON for ingestion, and pretty JSON for debugging simultaneously. - [Formats Example](/logly.zig/examples/formats.md): Example demonstrating all core serialization formats end to end with per-sink format selection in Logly.zig. - [Formatted Logging Example](/logly.zig/examples/formatted-logging.md): Example of printf-style formatted logging in Logly.zig using infof, debugf, warnf methods. Dynamic message construction with format strings and arguments. - [Time Formatting Example](/logly.zig/examples/time.md): Example of customizing timestamp formatting and timezones in Logly.zig. Switch between local and UTC time with standard date format strings. - [Log Filtering Example](/logly.zig/examples/filtering.md): Example of filtering logs with Logly.zig. Filter by level, module, message content with allow/deny rules and batch evaluation for precise log control. - [Log Sampling Example](/logly.zig/examples/sampling.md): Example of log sampling with Logly.zig. Control log volume using probability sampling, rate limiting, and every-Nth strategies for high-throughput applications. - [Log Redaction Example](/logly.zig/examples/redaction.md): Example of automatic sensitive data masking with Logly.zig. Redact passwords, API keys, credit cards, and PII for security and GDPR compliance. - [Logging Metrics Example](/logly.zig/examples/metrics.md): Example of collecting logging metrics with Logly.zig. Track record counts, bytes written, error rates, and per-level statistics for observability. - [Distributed Tracing Example](/logly.zig/examples/tracing.md): Example of distributed tracing with Logly.zig. Track requests across microservices with trace IDs, span IDs, correlation IDs, and OpenTelemetry compatibility. - [OpenTelemetry Example](/logly.zig/examples/telemetry.md): Comprehensive examples of OpenTelemetry integration with Logly.zig including spans, metrics, context propagation, and custom providers. - [Distributed Logging Example](/logly.zig/examples/distributed.md): A complete example of a simulated microservice using Logly.zig's distributed features. Shows configuration, trace propagation, and structured JSON output. - [Log Compression Example](/logly.zig/examples/compression.md): Example of log compression with Logly.zig using DEFLATE, GZIP, ZLIB, ZSTD, LZMA, LZMA2, XZ, TAR.GZ, ZIP, and LZ4 algorithms. Compress logs with CRC32 verification, configurable levels, and rotation integration. - [Thread Pool Example](/logly.zig/examples/thread-pool.md): Example of parallel log processing with Logly.zig thread pool. Configure worker threads, work stealing, batch submission, and priority-based task scheduling. - [Scheduler Example](/logly.zig/examples/scheduler.md): Example of automatic log maintenance with Logly.zig scheduler. Configure cleanup, compression, rotation, cron expressions, and custom periodic tasks. - [Dynamic Path Example](/logly.zig/examples/dynamic-path.md): Example of dynamic path formatting in Logly.zig. Use date and time placeholders like {date}, {YYYY}, {MM}, {DD} to create timestamped log file paths. - [Write Modes Example](/logly.zig/examples/write-modes.md): Example of controlling log file write modes in Logly.zig. Choose between append mode for persistent history or overwrite mode for fresh session logs. - [Append/Overwrite with Rotation](/logly.zig/examples/append-overwrite.md): Example of using append and overwrite write modes with file rotation in Logly.zig. Learn how different write modes interact with rotation configurations. - [Production Configuration Example](/logly.zig/examples/production-config.md): Enterprise-ready Logly.zig configurations for production. Includes presets for production, development, high-throughput, and secure environments with multi-sink architecture. - [Advanced Filtering Example](/logly.zig/examples/filter-advanced.md): Advanced Logly.zig filtering example covering glob rules, rate limiting, time-window rules, and batch filtering. - [Advanced Formatting Example](/logly.zig/examples/formatter-advanced.md): NDJSON, logfmt, syslog, and template formatting with Logly.zig. - [Advanced Sink Example](/logly.zig/examples/sink-advanced.md): In-memory ring sinks, atomic fan-out groups, and health plus rate limiting with Logly.zig. - [Advanced Redaction Example](/logly.zig/examples/redaction-advanced.md): Email, IP, JWT, and Luhn redaction with presets and compliance audit logging in Logly.zig. - [Global Crash & Panic Handler Example](/logly.zig/examples/crash-handler.md): Learn how to set up and trigger the global panic handler to prevent log loss during application crashes in Zig. - [Zero-Downtime Hot-Reload Example](/logly.zig/examples/hot-reload.md): Learn how to dynamically reload configurations at runtime without restarting processes or dropping log records. - [Memory-Mapped (mmap) Sinks Example](/logly.zig/examples/mmap.md): Learn how to set up and run memory-mapped sinks for ultra-high-performance virtual memory writes to disk. - [Dot-Notation Context Filtering Example](/logly.zig/examples/context-filter.md): Learn how to filter log records at runtime based on deep nested properties in the structured log context metadata. - [Customizations Example](/logly.zig/examples/customizations.md): Complete example of Logly.zig customizations including global root path, format structure, color customization, and highlighter patterns. - [Allocator Usage](/logly.zig/examples/allocator-strategies.md): How to use allocators with Logly.zig. - [Advanced Features Example](/logly.zig/examples/advanced-features.md): Explore Logly.zig advanced features including scoped loggers, custom themes, and pipeline controls. - [Advanced Async Logging Example](/logly.zig/examples/async-advanced.md): Deep dive into Logly.zig async logging with ring buffers, overflow policies, and throughput tuning. - [Color Options Example](/logly.zig/examples/color-options.md): Control Logly.zig colors globally, per sink, and per output type with tint.zig styling. - [Color Modes Example](/logly.zig/examples/color-modes.md): Horizontal whole-line, vertical per-column, and disabled color modes with Logly.zig. - [Compression Demo Example](/logly.zig/examples/compression-demo.md): Compare all Logly.zig compression algorithms side by side with ratios and roundtrips. - [Minimal Compression Example](/logly.zig/examples/compression-minimal.md): Minimal Logly.zig compression setup using builder methods and presets. - [Configuration Presets Example](/logly.zig/examples/config-presets.md): Try Logly.zig log-only, display-only, custom, and silent modes with enforced storage rules. - [Distributed JSON Example](/logly.zig/examples/distributed-json.md): Emit distributed trace context as JSON with Logly.zig trace and span IDs. - [JSON Logging Example](/logly.zig/examples/json-logging.md): Structured JSON logging with Logly.zig including context, trace IDs, and stack traces. - [Memory-Mapped Sink Example](/logly.zig/examples/mmap-sink.md): High-performance logging with Logly.zig memory-mapped file sinks. - [Advanced Network Logging Example](/logly.zig/examples/network-advanced.md): Advanced Logly.zig network logging with TCP/UDP helpers, syslog, and JSON fetching. - [Network Send Helpers Example](/logly.zig/examples/network-send-helpers.md): Send raw TCP logs and syslog UDP messages with Logly.zig network helpers. - [Pipeline Controls Example](/logly.zig/examples/pipeline-controls.md): Tune the Logly.zig logging pipeline with async, thread pool, metrics, rotation, and scheduler controls. - [Redaction Truncate Example](/logly.zig/examples/redaction-truncate.md): Truncate sensitive values to a fixed length with Logly.zig redaction. - [Rotation Helpers Example](/logly.zig/examples/rotation-helpers.md): Preview rotation paths, schedules, and dry-run checks with Logly.zig rotation helpers. - [Key-Based Sampling Example](/logly.zig/examples/sampling-key.md): Deterministic per-key sampling with Logly.zig so the same IDs always sample the same way. - [Sink Write Modes Example](/logly.zig/examples/sink-write-modes.md): Compare Logly.zig sink write modes append, overwrite, and append-rotate with rotation. - [Telemetry Metrics Export Example](/logly.zig/examples/telemetry-metrics-export.md): Export Logly.zig telemetry metrics to a JSONL file. - [Telemetry Metric Names Example](/logly.zig/examples/telemetry-metric-names.md): Export Logly.zig telemetry metric names with prefixing and sanitization. - [Minimal Telemetry Example](/logly.zig/examples/telemetry-mini.md): Minimal Logly.zig telemetry setup writing spans to a file. - [Tamper-Evident Chaining Example](/logly.zig/examples/tamper-evident.md): Cryptographic SHA-256 log record chaining in Logly.zig to guarantee audit log integrity. - [Stack Traces Example](/logly.zig/examples/stack-traces.md): Capturing and formatting stack traces for error and critical log records in Logly.zig. - [Runtime Configuration Override Example](/logly.zig/examples/runtime-config-override.md): Dynamic runtime configuration updates, per-sink overrides, and conflict resolution in Logly.zig.