LunarLog ships a comprehensive benchmark suite built on Google Benchmark v1.9.1. It measures every layer of the logging pipeline in isolation — throughput, template formatting, filter evaluation, sink I/O, enricher overhead — and a realistic end-to-end scenario that combines all of them.

Use these benchmarks to:

• Establish a performance baseline for your platform
• Compare sink types and formatter costs
• Measure the overhead of filters, enrichers, and tag routing
• Validate that configuration changes don't regress throughput

v1.22.0 replaces several hot-path deep copies with immutable snapshot sharing (std::shared_ptr<const T> + copy-on-write updates).

This change is internal only — public APIs and expected behavior are unchanged.

Benchmarks are opt-in and disabled by default. Enable them with the LUNARLOG_BUILD_BENCHMARKS CMake option:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DLUNARLOG_BUILD_BENCHMARKS=ON
cmake --build build --target lunar_log_bench

Google Benchmark is fetched automatically via FetchContent — no manual dependency installation required.

Important: Always build in Release mode for meaningful results. Debug builds include assertions, sanitizers, and no optimizations — timings will be 5-50x slower and not representative of production performance.

Minimal benchmark-only build:

cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DLUNARLOG_BUILD_BENCHMARKS=ON \
    -DLUNARLOG_BUILD_TESTS=OFF \
    -DLUNARLOG_BUILD_EXAMPLES=OFF
cmake --build build --target lunar_log_bench

./build/bench/lunar_log_bench

Use --benchmark_filter to run a subset by regex:

# Only throughput benchmarks
./build/bench/lunar_log_bench --benchmark_filter="BM_Log"

# Only sink benchmarks
./build/bench/lunar_log_bench --benchmark_filter="BM_Sink"

# Only filtering benchmarks
./build/bench/lunar_log_bench --benchmark_filter="BM_Filter"

# Specific benchmark
./build/bench/lunar_log_bench --benchmark_filter="BM_E2E_Realistic"

Export results to a JSON file for analysis or CI comparison:

./build/bench/lunar_log_bench \
    --benchmark_format=json \
    --benchmark_out=bench_results.json

For stable results, run multiple repetitions and report aggregates:

./build/bench/lunar_log_bench \
    --benchmark_format=json \
    --benchmark_out=bench_results.json \
    --benchmark_repetitions=5 \
    --benchmark_report_aggregates_only=true

Core message throughput under various conditions.

Template parsing, rendering, and caching.

Per-layer filter overhead.

Sink write cost across sink types and formatters.

All file sink benchmarks write to temp files and clean up after each run.

Per-enricher overhead.

Full-pipeline latency with a production-like configuration.

This benchmark calls flush() inside the loop, so it measures the full round-trip time from log call to all sinks having written — not just enqueue latency.

Google Benchmark reports several key metrics:

Throughput: items_per_second is the primary metric. Higher is better. Compare BM_LogInfo_SingleThread against BM_Sink_* benchmarks to isolate sink overhead.

Cache effectiveness: Compare BM_FormatCacheHit vs BM_FormatCacheMiss. If the miss penalty is large, consider increasing setTemplateCacheSize() for workloads with many distinct templates.

Filter scaling: Compare BM_Filter_DSL_1Rule → BM_Filter_DSL_5Rules → BM_Filter_DSL_10Rules to understand the per-rule cost. If overhead is significant, consolidate rules or use compact filters.

Sink comparison: Compare BM_Sink_Null → BM_Sink_File_HumanReadable → BM_Sink_File_Json → BM_Sink_File_CompactJson to see the formatter + I/O cost delta.

Enricher overhead: Subtract BM_Enricher_None from BM_Enricher_Three to see the total enricher cost. If it dominates your throughput budget, prefer cached enrichers (ProcessId, Property) over per-entry ones (ThreadId).

Contention: Compare single-thread vs multi-thread throughput in BM_LogInfo_MultiThread. The per-thread throughput drop indicates lock contention.

-----------------------------------------------------------------------
Benchmark                             Time       CPU  items_per_second
-----------------------------------------------------------------------
BM_LogInfo_SingleThread            245 ns    243 ns        4.1M/s
BM_LogTrace_Disabled              1.2 ns    1.2 ns      833.3M/s
BM_LogInfo_MultiThread/threads:4   312 ns    298 ns       13.4M/s
BM_FormatCacheHit                  230 ns    228 ns        4.4M/s
BM_FormatCacheMiss                 580 ns    575 ns        1.7M/s
BM_Sink_Null                       240 ns    238 ns        4.2M/s
BM_Sink_File_Json                  890 ns    620 ns        1.6M/s
BM_E2E_Realistic                  4200 ns   2100 ns      476.2K/s

(Numbers are illustrative — actual results depend on hardware, OS, and compiler.)

The benchmark suite includes null_sink.hpp — a minimal no-op sink used to isolate non-I/O overhead:

class NullSink : public ISink {
public:
    void write(const LogEntry&) override {}
};

Use it in your own benchmarks or tests when you need to measure pipeline cost without file I/O.

The bench.yml workflow runs benchmarks on every push and pull request to master:

name: Benchmarks
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:

What it does:

1. Configures a Release build with benchmarks enabled (tests and examples disabled)
2. Builds the lunar_log_bench target
3. Runs all benchmarks with 5 repetitions, aggregate-only reporting, JSON output
4. Uploads bench_results.json as a GitHub Actions artifact

The results artifact is available for download from the Actions tab on each workflow run.

Replicate the CI benchmark run on your machine:

cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DLUNARLOG_BUILD_BENCHMARKS=ON \
    -DLUNARLOG_BUILD_TESTS=OFF \
    -DLUNARLOG_BUILD_EXAMPLES=OFF
cmake --build build --target lunar_log_bench -j$(nproc)

./build/bench/lunar_log_bench \
    --benchmark_format=json \
    --benchmark_out=bench_results.json \
    --benchmark_repetitions=5 \
    --benchmark_report_aggregates_only=true

• Always benchmark in Release mode. Debug builds are 5-50x slower due to assertions and missing optimizations. Timings from Debug builds are not meaningful for performance analysis.
• Close other workloads during benchmarking. Background processes, browser tabs, and system updates introduce noise.
• Use --benchmark_repetitions=N (e.g. 5) for stable measurements. Google Benchmark reports mean, median, and stddev across repetitions.
• Use --benchmark_filter to focus on specific areas. Running the full suite takes longer; targeted runs give faster feedback during development.
• Compare items_per_second rather than raw nanoseconds when comparing across machines. Throughput is more portable than absolute timing.
• Benchmark your actual configuration. The suite tests isolated layers. For your specific setup (number of sinks, enrichers, filter rules), the E2E benchmark is the closest proxy — or write a custom benchmark targeting your exact config.

The suite includes benchmarks that call flush() at different intervals to measure end-to-end pipeline throughput (enqueue + consumer + sink write):

Rule of thumb: if your app flushes frequently (e.g. on every HTTP request), use FlushEvery1 numbers. For high-throughput logging, use FlushEvery1000.

Last updated: 2026-02-25 · Ubuntu (GitHub Actions) · 4 vCPU @ 3222 MHz · Release mode · Google Benchmark v1.9.1

Results vary by hardware. Run locally for your platform.