LunarLog

Header-only C++11 structured logging with message templates. Inspired by Serilog.

Quick Start

#include "lunar_log.hpp"
#include <lunar_log/macros.hpp>

int main() {
    // Fluent Builder — configure, add sinks, enrich, build
    auto logger = minta::LunarLog::configure()
        .minLevel(minta::LogLevel::DEBUG)
        .captureSourceLocation(true)
        .enrich(minta::Enrichers::threadId())
        .enrich(minta::Enrichers::property("service", "my-app"))
        .writeTo<minta::ConsoleSink>("console")
        .writeTo<minta::FileSink>("app-log", "app.log")
        .writeTo<minta::FileSink, minta::JsonFormatter>("json-out", "app.json.log")
        .build();

    // Message templates — named placeholders, structured properties
    logger.info("User {name} logged in from {ip}", "name", "alice", "ip", "10.0.0.1");

    // Source location macros — auto-capture __FILE__, __LINE__, __func__
    LUNAR_INFO(logger, "Order {id} processed: {items} items, total {total:.2f}",
               "id", "ORD-1234", "items", 3, "total", 59.97);

    return 0;
}

Why LunarLog?

• Structured logging — message templates with named placeholders, not printf. Properties are preserved in JSON/XML for machine processing.
• Zero dependencies — header-only, no external libraries. Just #include and go.
• C++11 and up — works with GCC, Clang, and MSVC. No C++17 required.
• Sync-first architecture — direct dispatch by default, async opt-in via AsyncSink decorator. No hidden threads or queues.
• Production-ready — thread-safe (CI-verified with ASan/TSan/UBSan), rate-limited, rolling file rotation, multi-layer filtering.
• Serilog-inspired — destructuring operators, enrichers, and fluent builder will feel familiar.

Performance note: LunarLog prioritizes structured logging capabilities over raw throughput. See Performance Tuning for honest benchmarks vs spdlog.

Features

• Message Templates — named & indexed placeholders with key-value or positional arguments, @/$ operators, format specifiers
• Output Formats — human-readable, JSON, Compact JSON (CLEF), XML
• Filtering — per-sink levels, predicates, DSL rules, compact syntax ("WARN+ ~timeout")
• Sinks — Console / ColorConsole (ConsoleStream::StdOut / ConsoleStream::StdErr), File, RollingFile, AsyncSink, BatchedSink, SyslogSink, HttpSink, CallbackSink — named sinks & tag routing
• Pipe Transforms — 18 built-in: upper, trim, comma, bytes, duration, truncate, chainable
• Enrichers — auto-attach ThreadId, ProcessId, MachineName, environment, custom lambdas
• Exception Attachment — logger.error(ex, "msg") with nested exception unwinding
• Fluent Builder — declarative LunarLog::configure().writeTo<>().enrich().build()
• Sub-Logger / Nested Pipeline — independent filters, enrichers, and sinks for complex routing (error alerts, audit trails)
• Dynamic Log Level — change levels, per-sink levels, and filters at runtime via LevelSwitch or config file watcher
• Global Logger — process-wide static facade: minta::Log::info("...")
• Source Location Macros — LUNAR_INFO(logger, ...) auto-captures __FILE__, __LINE__, __func__
• Scoped Context — RAII LogScope for request-lifetime fields
• Thread Safety, Rate Limiting — production-safe concurrency

Installation

Single header — download and include:

wget https://raw.githubusercontent.com/LunarECL/LunarLog/master/single_include/lunar_log.hpp

CMake FetchContent:

include(FetchContent)
FetchContent_Declare(LunarLog GIT_REPOSITORY https://github.com/LunarECL/LunarLog.git GIT_TAG v1.29.2)
FetchContent_MakeAvailable(LunarLog)
target_link_libraries(YourTarget PRIVATE LunarLog)

CMake subdirectory:

add_subdirectory(LunarLog)
target_link_libraries(YourTarget PRIVATE LunarLog)

Conan:

conan install --requires="lunarlog/1.29.2"

vcpkg (overlay port):

vcpkg install lunarlog --overlay-ports=path/to/LunarLog/ports

Full installation guide: Getting Started

Documentation

Guide	Description
Getting Started	Installation, first log, build setup
API Reference	Every public method with signatures and examples
Fluent Builder	Declarative logger configuration
Message Templates	Placeholders, operators, format specifiers
Filtering	Per-sink levels, predicates, DSL rules
Enrichers	Auto-attach metadata to every log entry
Performance Tuning	CI benchmark snapshot and practical tuning tips
Comparison	Honest comparison with spdlog, Boost.Log, and glog
Migrating from spdlog	API mapping and migration checklist
Building Your Own Sink	Step-by-step custom sink patterns
Cookbook	Real-world recipes and patterns
Benchmark Suite	Performance benchmarks and CI integration

Full wiki · Examples · Contributing

Performance

Benchmarks run in CI on every push (Release mode, Google Benchmark). The suite measures throughput, formatting, filtering, sink I/O, enrichers, and end-to-end latency.

Benchmark Suite

License

MIT — see LICENSE.