From 958c48c7247603816275af9c89f986c56fd96a75 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Tue, 8 Sep 2026 22:27:50 +0300 Subject: [PATCH 1/6] docs: add logging library comparison Document LogIt++ trade-offs and design differences against spdlog, Quill, Boost.Log, glog, and IceCream-Cpp. Keep the benchmark section limited to the reproducible LogIt++/spdlog fixture, provide English and Russian pages, and wire the canonical page into Doxygen and documentation smoke checks. --- .github/workflows/publish.yaml | 2 + Doxyfile | 1 + README-RU.md | 1 + README.md | 1 + docs/comparison-RU.md | 207 ++++++++++++++++++++++++++++++ docs/comparison.md | 224 +++++++++++++++++++++++++++++++++ docs/mainpage.dox | 1 + docs/quickstart.md | 2 + 8 files changed, 439 insertions(+) create mode 100644 docs/comparison-RU.md create mode 100644 docs/comparison.md diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index fc07d6c..26b2795 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -43,11 +43,13 @@ jobs: test -s docs/html/quickstart.html test -s docs/html/backends.html test -s docs/html/benchmarks.html + test -s docs/html/comparison.html test -s docs/html/api_reference.html grep -q "$DOC_VERSION" docs/html/index.html grep -q "Quick start" docs/html/index.html grep -q "Backend matrix" docs/html/index.html grep -q "Performance and benchmarks" docs/html/index.html + grep -q "Comparison with other C++ logging libraries" docs/html/index.html grep -q "API reference and concepts" docs/html/index.html grep -R -q "MemoryLogger" docs/html grep -R -q "MdbxLogger" docs/html diff --git a/Doxyfile b/Doxyfile index 8280f78..817af4f 100644 --- a/Doxyfile +++ b/Doxyfile @@ -957,6 +957,7 @@ INPUT = ./include \ ./docs/backends.md \ ./docs/reference.dox \ ./docs/benchmarks.md \ + ./docs/comparison.md \ ./docs/groups.dox \ ./docs/OtlpHttpLogger.md \ ./docs/PrometheusLogger.md \ diff --git a/README-RU.md b/README-RU.md index 0fe5328..8a4ff05 100644 --- a/README-RU.md +++ b/README-RU.md @@ -55,6 +55,7 @@ scope-замер. - [`docs/installation.md`](docs/installation.md) — установка через CMake, vendored и installed package сценарии. - [`docs/backends.md`](docs/backends.md) — матрица бэкендов, платформ, зависимостей и packaging. - [`docs/benchmarks.md`](docs/benchmarks.md) — методика benchmark и исторический snapshot. +- [`docs/comparison-RU.md`](docs/comparison-RU.md) — сравнение со spdlog, Quill, Boost.Log, glog и IceCream-Cpp. - [`docs/OtlpHttpLogger.md`](docs/OtlpHttpLogger.md) — OTLP/HTTP, callback-экспорт, атрибуты, retries, разбиение payload и сжатие. - [`docs/PrometheusLogger.md`](docs/PrometheusLogger.md) — payload/server-бэкенды, registry, scrape и ограничения. diff --git a/README.md b/README.md index 6ee7629..f41aaa5 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,7 @@ Detailed guides and documentation map: - [`docs/installation.md`](docs/installation.md) — CMake, vendored, installed-package, and package-manager setup. - [`docs/backends.md`](docs/backends.md) — backend, platform, dependency, and packaging matrix. - [`docs/benchmarks.md`](docs/benchmarks.md) — benchmark methodology and historical snapshot. +- [`docs/comparison.md`](docs/comparison.md) — comparison with spdlog, Quill, Boost.Log, glog, and IceCream-Cpp. - [`docs/OtlpHttpLogger.md`](docs/OtlpHttpLogger.md) — OTLP/HTTP and callback exporters, structured attributes, retries, splitting, and compression. - [`docs/PrometheusLogger.md`](docs/PrometheusLogger.md) — payload/server backends, registry metrics, scrape configuration, and limitations. diff --git a/docs/comparison-RU.md b/docs/comparison-RU.md new file mode 100644 index 0000000..e44ace9 --- /dev/null +++ b/docs/comparison-RU.md @@ -0,0 +1,207 @@ +# Сравнение LogIt++ с другими C++-библиотеками логирования + +Эта страница — сравнение архитектуры и возможностей, а не универсальный +рейтинг «кто лучше». Она отвечает на практический вопрос: **когда LogIt++ +подходит лучше компактного string-oriented логгера, общего event framework или +диагностической macro-утилиты?** + +Сравнение проверено **08.09.2026** по следующим upstream-релизам: + +| Проект | Проверенная версия | Основная документация | +| --- | --- | --- | +| LogIt++ | `1.0.2-dev` (`main`) | [документация проекта](https://liminode.github.io/log-it-cpp/) | +| spdlog | [`v1.17.0`](https://github.com/gabime/spdlog/releases/tag/v1.17.0) | [README](https://github.com/gabime/spdlog), [асинхронное логирование](https://github.com/gabime/spdlog/wiki/Asynchronous-logging) | +| Quill | [`v13.0.0`](https://github.com/odygrd/quill/releases/tag/v13.0.0) | [документация проекта](https://quillcpp.readthedocs.io/) | +| Boost.Log | [Boost `1.92.0`](https://www.boost.org/users/history/version_1_92_0.html) | [документация Boost.Log](https://www.boost.org/doc/libs/1_92_0/libs/log/doc/html/) | +| glog | [`v0.7.1`](https://github.com/google/glog/releases/tag/v0.7.1) | [документация glog](https://google.github.io/glog/) | +| IceCream-Cpp | [`v1.0.0`](https://github.com/renatoGarcia/icecream-cpp/releases/tag/v1.0.0) | [README проекта](https://github.com/renatoGarcia/icecream-cpp) | + +Upstream-проекты развиваются независимо. Перед принятием решения о внедрении +нужно повторно проверить версии и ссылки. + +## На что оптимизирован LogIt++ + +LogIt++ строится вокруг диагностической записи, а не только готовой строки. +Обычный macro-вызов может сохранить значения и имена аргументов для форматтеров, +memory/storage-бэкендов, callback-ов и telemetry exporters. Тот же macro-first +API покрывает условное логирование, throttling, scope timers, tags, MDC/NDC и +маршрутизацию в конкретный logger. + +Это удобно, когда логирование является частью диагностического data flow +приложения. Если требуется только минимальная стоимость вывода заранее +сформатированной строки, более узкий логгер может оказаться подходящим выбором. + +## Сравнение возможностей + +Таблица описывает основную поставку и документированный API проверенных версий, +а не все возможности, которые можно получить через сторонние adapters. + +- **Built in** — возможность прямо документирована в библиотеке; +- **Different model** — похожий результат достигается другой абстракцией; +- **Extension** — обычно нужен adapter, custom sink или код приложения; +- `—` — это не основная цель проекта, а не утверждение о невозможности + реализовать такую функцию. + +| Возможность | LogIt++ | spdlog | Quill | Boost.Log | glog | IceCream-Cpp | +| --- | --- | --- | --- | --- | --- | --- | +| Macro-first instrumentation | Built in | Built in macros | Built in macros | Другая модель | Built in macros | Основная функция | +| Structured records / attributes | Built in `LogRecord` и values | Другая модель: строки и formatter arguments | Другая модель: typed async messages | Built in attributes/events | Extension / message-centric | Диагностические values, не sink record | +| Захват имён аргументов | Built in | — | — | — | — | Built in | +| `printf` и stream API | Built in | Built in | Built in / fmt-oriented | Extension / другая модель | Stream и printf-подобные macros | Человекочитаемый вывод | +| Conditional и rate-limited macros | Built in | Built in macro families | Зависит от API | Filters и predicates | Built in severity/condition macros | Ограниченные diagnostic helpers | +| Асинхронная очередь | Built in | Built in | Основная архитектура | Зависит от sink-а | Не основная модель | — | +| Настраиваемый overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Queue policies документированы | Зависит от sink/configuration | — | — | +| Rotating file sink | Built in | Built in | Built in handlers | Built in sink types | Базовые файлы; rotation — отдельная задача | — | +| In-memory history и read-back | Built in для выбранных backend-ов | Extension | Extension | Extension / custom sink | — | — | +| Live subscriptions | Built in для выбранных backend-ов | Extension | Extension | Extension | — | — | +| Persistent structured storage | Опциональный MDBX backend | Extension | Extension | Extension | — | — | +| OTLP и Prometheus | Опциональные встроенные backend-ы | Extension / adapter | Extension / adapter | Extension / adapter | Extension / adapter | — | +| Header-only integration | Built in | Поддерживаемый режим | CMake/library integration | Compiled Boost component | CMake/library integration | Header-oriented utility | + +Слово «встроенный» используется намеренно узко. Все эти проекты можно соединять +с другими sink-ами и telemetry-системами кодом приложения, но это не делает такую +интеграцию частью основной поставки. + +## Удобство API и syntactic sugar + +LogIt++ сознательно предоставляет большую регулярную поверхность macros: + +```cpp +#include + +LOGIT_INFO("Connected", host, port); +LOGIT_WARN_ONCE("configuration missing"); +LOGIT_INFO_EVERY_N(100, "processed", count); +LOGIT_ERROR_THROTTLE(1000, "connection still unavailable"); +LOGIT_SCOPE_INFO("load_database"); +LOGIT_INFO_TAG(({{"order_id", order_id}, {"symbol", symbol}}), "order sent"); +``` + +Первый вызов может сохранить имена и значения `host` и `port` — в зависимости от +выбранного macro и build options. Это удобнее для диагностики, но требует больше +работы, чем минимальный вызов с готовой строкой. + +У spdlog, Quill и glog тоже есть полезные macro families, однако их основные +абстракции — logger calls, formatted messages или severity/check macros. Boost.Log +делает акцент на records, attributes, filters и sinks, а не на едином macro facade. +IceCream-Cpp ближе всего к LogIt++ в части показа имён аргументов, но не является +framework-ом logger backend-ов. + +## Почему IceCream-Cpp — особый случай + +IceCream-Cpp — утилита для diagnostic printing и introspection. Она полезна, +когда разработчику нужен короткий вызов, показывающий выражение и его значение: + +```cpp +// Диагностический вывод в стиле IceCream-Cpp +IC(x, user_id); +``` + +IceCream-Cpp не пытается предоставлять sinks, asynchronous queues, file rotation, +retention/read-back, subscriptions, OTLP или Prometheus backends. Поэтому здесь +имеет смысл сравнивать ergonomics и захват имён аргументов, а не количество sink-ов. +IceCream-Cpp может использоваться вместе с настоящим logger-ом. + +## Асинхронная доставка и очереди + +LogIt++ поддерживает synchronous и asynchronous режимы, общий и dedicated +executor, размер очереди и явные overflow policies. Для deque и MPSC намеренно +задокументирована разная семантика: в MPSC `DropOldest` отбрасывает входящую +задачу, сохраняя порядок уже принятых задач. + +spdlog и Quill ближе всего для сравнений асинхронной производительности и настройки +очереди. Их topology workers, options и overflow semantics нельзя автоматически +считать эквивалентными LogIt++. Boost.Log позволяет строить асинхронные pipeline +через sinks и backends, но имеет более общий configuration model. glog и +IceCream-Cpp не являются прямыми аналогами этой queue architecture. + +## Structured data, storage и telemetry + +LogIt++ особенно уместен, когда log record нужен после самого вызова: + +- `MemoryLogger` поддерживает snapshots, readers и subscribers; +- file и MDBX backends могут сохранять structured records; +- OTLP exporters передают выбранные structured attributes и context; +- Prometheus backends публикуют application и built-in metrics; +- MDC/NDC, tags и argument values проходят через одну record model. + +Ближайший архитектурный аналог здесь — Boost.Log с его extensible records, +attributes, filters и sinks. spdlog и Quill обычно проще для formatted messages +и high-throughput sinks. glog сознательно сфокусирован на application diagnostics +и severity/check macros. Это trade-offs области применения, а не универсальный +рейтинг библиотек. + +## Снимок производительности + +Сейчас в репозитории есть воспроизводимый adapter только для LogIt++ и spdlog, +а не для всех шести проектов. Поэтому таблица — **снимок LogIt++/spdlog +pipeline**, а не рейтинг всех библиотек. + +| Режим | Sink | LogIt++ p50 | LogIt++ throughput | spdlog p50 | spdlog throughput | +| --- | --- | ---: | ---: | ---: | ---: | +| Sync | Null | 119 ns | 2 127 704 msg/s | 86 ns | 5 803 783 msg/s | +| Sync | File | 130 ns | 1 035 690 msg/s | 87 ns | 1 593 987 msg/s | +| Async | Null | 20 916 ns | 1 846 272 msg/s | 1 248 779 ns | 1 303 573 msg/s | +| Async | File | 255 323 ns | 651 384 msg/s | 5 001 140 ns | 1 153 976 msg/s | + +Условия snapshot: Release build, четыре producer-а, сообщения по 200 байт, +`LOGIT_BENCH_TOTAL=10000`, fixture от 05.12.2025. Путь LogIt++ может включать +извлечение имён аргументов и упаковку structured values, а spdlog adapter получает +готовую строку. Async-результаты также включают enqueue, wake-up/scheduling worker-а +и работу sink-а. + +Методика описана в [`docs/benchmarks.md`](benchmarks.html), полный fixture — в +[`latency-2025-12-05-10k.csv`](https://github.com/LimiNode/log-it-cpp/blob/main/bench/results/latency-2025-12-05-10k.csv). +Harness пока не измеряет allocations на сообщение, binary size, compile time или +сопоставимые сценарии Quill/Boost.Log/glog; эти цифры здесь не выдумываются. + +## Trade-offs + +- поверхность macros намеренно широкая; +- захват имён аргументов и structured records могут стоить дороже минимального + вызова с готовой строкой; +- OTLP, Prometheus HTTP server и MDBX требуют C++17; +- optional dependencies и installed-package composition требуют настроек CMake; +- публичный API использует aggregate-first umbrella headers, а не обещает + standalone-включение каждого leaf-заголовка; +- приоритет — диагностическая насыщенность, storage и telemetry, а не абсолютный + минимум overhead одного logging call. + +## Как выбрать библиотеку + +**Выбирайте LogIt++, если:** + +- нужен один macro-first API для console, file, memory, storage и telemetry; +- важны structured values, захват имён аргументов, tags, MDC/NDC или read-back; +- важны queue capacity, overflow policy, dedicated executors и поведение разных + backend-ов; +- подходит header-only C++11 core с отдельными C++17 integrations. + +**Рассмотрите spdlog или Quill, если:** + +- главное — сфокусированный быстрый pipeline для formatted messages; +- подходят их sinks, queue design или ecosystem; +- хранить structured diagnostic records не требуется. + +**Рассмотрите Boost.Log, если:** + +- важнее общий framework attributes/filters/sinks, чем компактный macro facade; +- проект уже использует Boost и нужен его extensibility model. + +**Рассмотрите glog, если:** + +- нужны прежде всего Google-style severity, check и diagnostic macros; +- узкая application logging model предпочтительнее storage и telemetry backend-ов. + +**Рассмотрите IceCream-Cpp, если:** + +- нужен лёгкий introspection исходных выражений во время разработки; +- logger/sink/retention framework не нужен. IceCream-Cpp может дополнять, а не + заменять, одну из logging libraries выше. + +## Источники и воспроизводимость + +Ссылки на версии и upstream-документацию находятся в английской canonical-версии +этой страницы. Для поведения LogIt++ используйте guides, generated API reference, +examples и benchmark fixture репозитория. Перед performance decision повторяйте +измерения на целевых compiler, OS, hardware, sink, queue configuration и workload. diff --git a/docs/comparison.md b/docs/comparison.md new file mode 100644 index 0000000..4aef738 --- /dev/null +++ b/docs/comparison.md @@ -0,0 +1,224 @@ +\page comparison Comparison with other C++ logging libraries + +# LogIt++ compared with other C++ logging libraries + +This page is a design and feature comparison, not a universal ranking. It +answers a practical question: **when does LogIt++ fit better than a smaller +formatted-string logger, a general event framework, or a diagnostic macro +utility?** + +The comparison was checked on **2026-09-08** against these upstream releases: + +| Project | Release checked | Primary documentation | +| --- | --- | --- | +| LogIt++ | `1.0.2-dev` (`main`) | [project documentation](https://liminode.github.io/log-it-cpp/) | +| spdlog | [`v1.17.0`](https://github.com/gabime/spdlog/releases/tag/v1.17.0) | [README](https://github.com/gabime/spdlog), [async logging](https://github.com/gabime/spdlog/wiki/Asynchronous-logging) | +| Quill | [`v13.0.0`](https://github.com/odygrd/quill/releases/tag/v13.0.0) | [project documentation](https://quillcpp.readthedocs.io/) | +| Boost.Log | [Boost `1.92.0`](https://www.boost.org/users/history/version_1_92_0.html) | [Boost.Log documentation](https://www.boost.org/doc/libs/1_92_0/libs/log/doc/html/) | +| glog | [`v0.7.1`](https://github.com/google/glog/releases/tag/v0.7.1) | [glog documentation](https://google.github.io/glog/) | +| IceCream-Cpp | [`v1.0.0`](https://github.com/renatoGarcia/icecream-cpp/releases/tag/v1.0.0) | [project README](https://github.com/renatoGarcia/icecream-cpp) | + +Upstream projects evolve independently. Re-check the release and linked +documentation before using this page as a procurement or performance claim. + +## What LogIt++ optimizes for + +LogIt++ is designed around a diagnostic record rather than only a finished +string. A normal macro call can keep values and argument names available to +formatters, memory/storage backends, callbacks, and telemetry exporters. The +same macro-first surface also covers conditional logging, throttling, scope +timers, tags, MDC/NDC context, and targeted logger routing. + +This makes LogIt++ a good fit when logging is part of an application's +diagnostic data flow. It is a less obvious fit when the only requirement is the +smallest possible formatted-string call on a hot path. + +## Feature comparison + +The table describes the primary distribution and documented API of each +project, not everything that can be built through third-party adapters. `Built +in` means the checked release documents the capability directly. `Different +model` means that a similar outcome exists, but the abstraction is not +equivalent. `Extension` means that an adapter, custom sink, or application +code is normally required. A dash means that the capability is not a primary +goal of the checked project, not that it is impossible to implement. + +| Capability | LogIt++ | spdlog | Quill | Boost.Log | glog | IceCream-Cpp | +| --- | --- | --- | --- | --- | --- | --- | +| Macro-first instrumentation | Built in | Built in macros | Built in macros | Different model | Built in macros | Core feature | +| Structured records / attributes | Built in `LogRecord` and values | Different model: formatted message and formatter arguments | Different model: typed async log messages | Built in attribute/event model | Extension / message-centric | Diagnostic values, not a sink record | +| Capture source argument names | Built in | — | — | — | — | Built in | +| `printf`-style and stream APIs | Built in | Built in | Built in / fmt-oriented | Extension / different model | Stream and printf-like macros | Human-readable display | +| Conditional and rate-limited macros | Built in | Built in macro families | API-dependent | Filters and predicates | Built in severity/condition macros | Limited diagnostic helpers | +| Asynchronous queue | Built in | Built in | Core design | Sink-dependent | Not the primary model | — | +| Configurable overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Queue policies documented by Quill | Sink/configuration dependent | — | — | +| Rotating file sink | Built in | Built in | Built in handlers | Built in sink types | Basic file logging; rotation is a different concern | — | +| In-memory history and read-back | Built in for selected backends | Extension | Extension | Extension / custom sink | — | — | +| Live log subscriptions | Built in for selected backends | Extension | Extension | Extension | — | — | +| Persistent structured storage | Built in optional MDBX backend | Extension | Extension | Extension | — | — | +| OTLP and Prometheus integrations | Built in optional backends | Extension / adapter | Extension / adapter | Extension / adapter | Extension / adapter | — | +| Header-only integration | Built in | Supported mode | CMake/library integration | Compiled Boost component | CMake/library integration | Header-oriented utility | + +The word “built in” is intentionally narrow. For example, all of these +projects can be connected to other sinks or telemetry systems by application +code; that does not make the integration part of the primary distribution. + +## Developer ergonomics + +LogIt++ deliberately provides a large, regular macro surface: + +```cpp +#include + +LOGIT_INFO("Connected", host, port); +LOGIT_WARN_ONCE("configuration missing"); +LOGIT_INFO_EVERY_N(100, "processed", count); +LOGIT_ERROR_THROTTLE(1000, "connection still unavailable"); +LOGIT_SCOPE_INFO("load_database"); +LOGIT_INFO_TAG(({{"order_id", order_id}, {"symbol", symbol}}), "order sent"); +``` + +The first call can retain the names and values of `host` and `port`, depending +on the selected macro and build options. That is different from passing one +already formatted string to a sink. It is convenient for diagnostics, but it +also does more work than a minimal formatted-string call. + +spdlog, Quill, and glog also provide useful macro families, but their primary +abstractions remain logger calls, formatted messages, or severity/check +macros. Boost.Log emphasizes records, attributes, filters, and sinks rather +than a single macro facade. IceCream-Cpp is the closest comparison for +argument-name display, but it deliberately stops short of being a logger +backend framework. + +## Why IceCream-Cpp is a different comparison + +IceCream-Cpp is a diagnostic printing/introspection utility. It is valuable +when a developer wants a short call that displays an expression and its value: + +```cpp +// IceCream-Cpp-style diagnostic output +IC(x, user_id); +``` + +It does not aim to provide LogIt++-style sinks, asynchronous queues, file +rotation, retention/read-back, subscriptions, OTLP, or Prometheus backends. +The meaningful comparison is therefore the ergonomics of source-level +diagnostics and argument-name capture, not “which logger has more sinks”. +IceCream-Cpp can also be used alongside a real logger. + +## Async delivery and queue semantics + +LogIt++ offers synchronous and asynchronous modes, global or dedicated +executors, queue capacity, and explicit overflow policies. The deque and MPSC +implementations intentionally document a semantic difference: in MPSC mode +`DropOldest` rejects the incoming task to preserve the order of already +accepted work. + +spdlog and Quill are closer comparisons for asynchronous throughput and queue +configuration. Their options, worker topology, and overflow semantics are +not interchangeable with LogIt++, so a benchmark must hold the workload and +delivery contract constant. Boost.Log can express asynchronous pipelines +through sinks and backends, but its configuration model is more general. glog +and IceCream-Cpp are not primary comparisons for this queue design. + +## Structured data, storage, and telemetry + +Choose LogIt++ when the log record itself is useful after the logging call: + +- `MemoryLogger` supports snapshots, readers, and subscribers; +- file and MDBX backends can retain structured records for later access; +- OTLP exporters preserve selected structured attributes and context; +- Prometheus backends expose application and built-in metrics; +- MDC/NDC, tags, and argument values can flow through the same record model. + +Boost.Log is the closest architectural comparison for an extensible record, +attribute, filter, and sink pipeline. spdlog and Quill are usually simpler to +adopt for formatted messages and high-throughput sinks. glog is intentionally +focused on application diagnostics and severity/check macros. These are +trade-offs in scope, not a claim that one design is universally better. + +## Performance snapshot + +The repository currently has a reproducible adapter for LogIt++ and spdlog, +not for every project in the feature table. The historical fixture below is +therefore a **LogIt++/spdlog pipeline snapshot**, not a ranking of all six +projects. + +| Mode | Sink | LogIt++ p50 | LogIt++ throughput | spdlog p50 | spdlog throughput | +| --- | --- | ---: | ---: | ---: | ---: | +| Sync | Null | 119 ns | 2,127,704 msg/s | 86 ns | 5,803,783 msg/s | +| Sync | File | 130 ns | 1,035,690 msg/s | 87 ns | 1,593,987 msg/s | +| Async | Null | 20,916 ns | 1,846,272 msg/s | 1,248,779 ns | 1,303,573 msg/s | +| Async | File | 255,323 ns | 651,384 msg/s | 5,001,140 ns | 1,153,976 msg/s | + +Snapshot conditions: Release build, four producers, 200-byte messages, +`LOGIT_BENCH_TOTAL=10000`, and the fixture recorded on 2025-12-05. The LogIt++ +path may include argument-name extraction and structured value packing, while +the spdlog adapter receives a prepared string. Async values also include +enqueue, worker wake-up/scheduling, and sink work. + +See [`docs/benchmarks.md`](benchmarks.html) for the methodology and +[`bench/results/latency-2025-12-05-10k.csv`](https://github.com/LimiNode/log-it-cpp/blob/main/bench/results/latency-2025-12-05-10k.csv) +for the complete fixture. The harness does not currently measure allocations +per message, binary size, compile time, or comparable Quill/Boost.Log/glog +scenarios; those numbers are intentionally not invented here. + +## Trade-offs + +Choose LogIt++ with its trade-offs in mind: + +- the macro surface is intentionally broad; +- argument-name capture and structured records can cost more than a minimal + preformatted-string call; +- optional OTLP, Prometheus HTTP server, and MDBX integrations use C++17; +- optional dependencies and installed-package composition need the documented + CMake setup; +- the public API uses aggregate-first umbrella headers rather than promising + that every leaf header is independently includable; +- the project favors diagnostic richness, storage, and telemetry integration + over the smallest possible logging-call overhead. + +## Which library should I choose? + +**Choose LogIt++ when:** + +- one macro-first API should cover console, file, memory, storage, and + telemetry backends; +- structured values, argument-name capture, tags, MDC/NDC, or read-back are + important; +- queue capacity, overflow policy, dedicated executors, and per-backend + delivery behavior matter; +- a header-only C++11 core with optional C++17 integrations fits the project. + +**Consider spdlog or Quill when:** + +- the main requirement is a focused, fast formatted-message pipeline; +- their existing sinks, queue design, or ecosystem match the application; +- retaining structured diagnostic records is not necessary. + +**Consider Boost.Log when:** + +- a general attribute/filter/sink framework is more important than a compact + macro facade; +- the project already depends on Boost and wants its extensibility model. + +**Consider glog when:** + +- Google-style severity, check, and diagnostic macros are the primary need; +- a narrower application logging model is preferable to storage and telemetry + backends. + +**Consider IceCream-Cpp when:** + +- the goal is lightweight source-expression introspection during development; +- a logger/sink/retention framework is not required. It can complement, rather + than replace, one of the logging libraries above. + +## Sources and reproducibility + +The version and source links at the top of this page are the authoritative +starting points for the feature comparison. For LogIt++ behavior, prefer the +linked project guides, generated API reference, examples, and benchmark +fixture in this repository. Re-run benchmarks on the target compiler, +operating system, hardware, sink, queue configuration, and workload before +making a performance decision. diff --git a/docs/mainpage.dox b/docs/mainpage.dox index 14c9b2f..126c93d 100644 --- a/docs/mainpage.dox +++ b/docs/mainpage.dox @@ -31,6 +31,7 @@ int main() { - \ref benchmarks — benchmark methodology and historical snapshot. - \ref api_reference — detailed macro, formatting, configuration, and extension reference. +- \ref comparison — comparison with other C++ logging libraries and trade-offs. \section feature_summary Feature summary - Macro families cover direct, printf-style, stream, conditional, throttled, diff --git a/docs/quickstart.md b/docs/quickstart.md index 66b871e..d238f35 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -38,6 +38,8 @@ dependency requirements are described in the [`Backend matrix`](backends.html). [`Queue back-pressure`](backpressure.html). - **Performance** — [`Benchmarks`](benchmarks.html), including methodology and the historical snapshot disclaimer. +- **Choosing a logging library** — [`Comparison with other C++ logging libraries`](comparison.html), + including trade-offs and the scope of the comparison. - **Examples** — browse the `examples/` directory in the source repository; each optional example states the feature macro it requires. From 2cb90f66cb2f75c81638c02ace4f8a036e9a851b Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Tue, 8 Sep 2026 22:28:50 +0300 Subject: [PATCH 2/6] docs: refine logging comparison wording Describe glog's stream-oriented macro surface without implying a printf API that the checked release does not document. --- docs/comparison-RU.md | 2 +- docs/comparison.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/comparison-RU.md b/docs/comparison-RU.md index e44ace9..68ba0c4 100644 --- a/docs/comparison-RU.md +++ b/docs/comparison-RU.md @@ -47,7 +47,7 @@ API покрывает условное логирование, throttling, scop | Macro-first instrumentation | Built in | Built in macros | Built in macros | Другая модель | Built in macros | Основная функция | | Structured records / attributes | Built in `LogRecord` и values | Другая модель: строки и formatter arguments | Другая модель: typed async messages | Built in attributes/events | Extension / message-centric | Диагностические values, не sink record | | Захват имён аргументов | Built in | — | — | — | — | Built in | -| `printf` и stream API | Built in | Built in | Built in / fmt-oriented | Extension / другая модель | Stream и printf-подобные macros | Человекочитаемый вывод | +| `printf` и stream API | Built in | Built in | Built in / fmt-oriented | Extension / другая модель | Stream-oriented macros | Человекочитаемый вывод | | Conditional и rate-limited macros | Built in | Built in macro families | Зависит от API | Filters и predicates | Built in severity/condition macros | Ограниченные diagnostic helpers | | Асинхронная очередь | Built in | Built in | Основная архитектура | Зависит от sink-а | Не основная модель | — | | Настраиваемый overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Queue policies документированы | Зависит от sink/configuration | — | — | diff --git a/docs/comparison.md b/docs/comparison.md index 4aef738..8d7e071 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -48,7 +48,7 @@ goal of the checked project, not that it is impossible to implement. | Macro-first instrumentation | Built in | Built in macros | Built in macros | Different model | Built in macros | Core feature | | Structured records / attributes | Built in `LogRecord` and values | Different model: formatted message and formatter arguments | Different model: typed async log messages | Built in attribute/event model | Extension / message-centric | Diagnostic values, not a sink record | | Capture source argument names | Built in | — | — | — | — | Built in | -| `printf`-style and stream APIs | Built in | Built in | Built in / fmt-oriented | Extension / different model | Stream and printf-like macros | Human-readable display | +| `printf`-style and stream APIs | Built in | Built in | Built in / fmt-oriented | Extension / different model | Stream-oriented macros | Human-readable display | | Conditional and rate-limited macros | Built in | Built in macro families | API-dependent | Filters and predicates | Built in severity/condition macros | Limited diagnostic helpers | | Asynchronous queue | Built in | Built in | Core design | Sink-dependent | Not the primary model | — | | Configurable overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Queue policies documented by Quill | Sink/configuration dependent | — | — | From 04febf0cea919a3c741472c1394cb2ffd5d9fb6e Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Tue, 8 Sep 2026 22:29:21 +0300 Subject: [PATCH 3/6] docs: keep comparison in landing page map Keep the new comparison page in the same Doxygen documentation list as the other guides. --- docs/mainpage.dox | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/mainpage.dox b/docs/mainpage.dox index 126c93d..4d28f25 100644 --- a/docs/mainpage.dox +++ b/docs/mainpage.dox @@ -30,7 +30,6 @@ int main() { - \ref backpressure — queue policies and drop counters. - \ref benchmarks — benchmark methodology and historical snapshot. - \ref api_reference — detailed macro, formatting, configuration, and extension reference. - - \ref comparison — comparison with other C++ logging libraries and trade-offs. \section feature_summary Feature summary From 48ff7a89f4e7e3b6ca08806e87d40a1476339201 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Tue, 8 Sep 2026 22:30:41 +0300 Subject: [PATCH 4/6] docs: separate landing page sections Keep the comparison link and feature summary as distinct Doxygen sections for a clearer generated landing page. --- docs/mainpage.dox | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/mainpage.dox b/docs/mainpage.dox index 4d28f25..21366c5 100644 --- a/docs/mainpage.dox +++ b/docs/mainpage.dox @@ -31,6 +31,7 @@ int main() { - \ref benchmarks — benchmark methodology and historical snapshot. - \ref api_reference — detailed macro, formatting, configuration, and extension reference. - \ref comparison — comparison with other C++ logging libraries and trade-offs. + \section feature_summary Feature summary - Macro families cover direct, printf-style, stream, conditional, throttled, From 41341f519305293e360affcf28fe9a154eba77b0 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Thu, 10 Sep 2026 14:52:08 +0300 Subject: [PATCH 5/6] docs: correct logging comparison matrix Align the English and Russian comparison pages with the checked upstream capabilities. Cover Quill named values, rate limiting, structured output, and Prometheus support; distinguish formatting and telemetry models; clarify Boost.Log queues, glog lifecycle, and LogIt++ storage semantics. --- docs/comparison-RU.md | 73 +++++++++++++++++++++++++++--------------- docs/comparison.md | 74 +++++++++++++++++++++++++++---------------- 2 files changed, 94 insertions(+), 53 deletions(-) diff --git a/docs/comparison-RU.md b/docs/comparison-RU.md index 68ba0c4..436c9bb 100644 --- a/docs/comparison-RU.md +++ b/docs/comparison-RU.md @@ -5,7 +5,7 @@ подходит лучше компактного string-oriented логгера, общего event framework или диагностической macro-утилиты?** -Сравнение проверено **08.09.2026** по следующим upstream-релизам: +Сравнение проверено **10.09.2026** по следующим upstream-релизам: | Проект | Проверенная версия | Основная документация | | --- | --- | --- | @@ -44,18 +44,22 @@ API покрывает условное логирование, throttling, scop | Возможность | LogIt++ | spdlog | Quill | Boost.Log | glog | IceCream-Cpp | | --- | --- | --- | --- | --- | --- | --- | -| Macro-first instrumentation | Built in | Built in macros | Built in macros | Другая модель | Built in macros | Основная функция | -| Structured records / attributes | Built in `LogRecord` и values | Другая модель: строки и formatter arguments | Другая модель: typed async messages | Built in attributes/events | Extension / message-centric | Диагностические values, не sink record | -| Захват имён аргументов | Built in | — | — | — | — | Built in | -| `printf` и stream API | Built in | Built in | Built in / fmt-oriented | Extension / другая модель | Stream-oriented macros | Человекочитаемый вывод | -| Conditional и rate-limited macros | Built in | Built in macro families | Зависит от API | Filters и predicates | Built in severity/condition macros | Ограниченные diagnostic helpers | -| Асинхронная очередь | Built in | Built in | Основная архитектура | Зависит от sink-а | Не основная модель | — | -| Настраиваемый overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Queue policies документированы | Зависит от sink/configuration | — | — | -| Rotating file sink | Built in | Built in | Built in handlers | Built in sink types | Базовые файлы; rotation — отдельная задача | — | -| In-memory history и read-back | Built in для выбранных backend-ов | Extension | Extension | Extension / custom sink | — | — | -| Live subscriptions | Built in для выбранных backend-ов | Extension | Extension | Extension | — | — | -| Persistent structured storage | Опциональный MDBX backend | Extension | Extension | Extension | — | — | -| OTLP и Prometheus | Опциональные встроенные backend-ы | Extension / adapter | Extension / adapter | Extension / adapter | Extension / adapter | — | +| Macro-first instrumentation | Built in | Встроенные severity macros | Built in macros | Встроенные macros над моделью records/streams | Built in macros | Основная функция | +| Structured records / attributes | Built in `LogRecord` и values | Formatted messages и MDC (только synchronous logging); другая record model | Встроенные named-value logging, JSON output, tags и MDC; другая record model | Built in attributes/events | Extension / message-centric | Диагностические values, не sink record | +| Захват имён аргументов | Built in | — | Built in через `LOGV_*` | — | — | Основная функция | +| Форматирование в стиле `{fmt}` | Built in при `LOGIT_WITH_FMT=ON` | Built in | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | — | +| Логирование в стиле `printf` | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | Extension / предварительное форматирование | Built in через низкоуровневый `RAW_LOG` | — | +| Логирование в стиле stream | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | Built in | Built in | Диагностический вывод, не stream API | +| Условное логирование | Built in | Нет специального helper-а; используется условие приложения | Нет специального helper-а; используется условие приложения | Filters и predicates; нет аналогичного call-site macro | Built in через `LOG_IF` | Configuration helpers, не logging framework | +| Rate-limited logging | Built in | Нет специального семейства macros | Built in через `LOG_*_LIMIT` и `LOGV_*_LIMIT` | Extension / custom filter | Built in через `LOG_EVERY_N`, `LOG_FIRST_N` и связанные macros | — | +| Асинхронная очередь | Built in | Built in | Основная архитектура | Built in через asynchronous sink frontends | Не основная модель | — | +| Настраиваемый overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Встроенные bounded/unbounded и blocking/dropping queue modes | Built in через bounded async sink queue strategies (`drop_on_overflow`, `block_on_overflow`) | — | — | +| Rotating file sink | Built in | Built in | Built in через `RotatingFileSink` | Built in sink types | Встроенные file rollover/cleanup; другая модель | — | +| In-memory history и read-back | Built in для выбранных backend-ов | Встроенный backtrace buffer; нет аналогичного read-back API | Встроенный backtrace logging; нет аналогичного read-back API | Extension / custom sink | — | — | +| Live subscriptions | Built in для выбранных backend-ов | Встроенный callback sink; другая модель | Extension / custom sink | Extension / custom sink | — | — | +| Встроенное queryable structured storage | Built in через опциональный MDBX backend | Extension | Extension | Extension | — | — | +| Экспорт логов через OTLP / OpenTelemetry | Опциональный встроенный backend | Extension / adapter | Extension / custom sink | Extension / adapter | Extension / adapter | — | +| Prometheus metrics | Опциональные встроенные backend-ы | Extension / adapter | Built in через `PrometheusSink` | Extension / adapter | Extension / adapter | — | | Header-only integration | Built in | Поддерживаемый режим | CMake/library integration | Compiled Boost component | CMake/library integration | Header-oriented utility | Слово «встроенный» используется намеренно узко. Все эти проекты можно соединять @@ -83,9 +87,10 @@ LOGIT_INFO_TAG(({{"order_id", order_id}, {"symbol", symbol}}), "order sent"); У spdlog, Quill и glog тоже есть полезные macro families, однако их основные абстракции — logger calls, formatted messages или severity/check macros. Boost.Log -делает акцент на records, attributes, filters и sinks, а не на едином macro facade. -IceCream-Cpp ближе всего к LogIt++ в части показа имён аргументов, но не является -framework-ом logger backend-ов. +предоставляет logging macros над своей моделью records, attributes, filters и +sinks, а не единый широкий macro facade. IceCream-Cpp ближе всего как отдельная +introspection-утилита; Quill также захватывает имена исходных переменных через +logging macros `LOGV_*`. ## Почему IceCream-Cpp — особый случай @@ -111,25 +116,28 @@ executor, размер очереди и явные overflow policies. Для de spdlog и Quill ближе всего для сравнений асинхронной производительности и настройки очереди. Их topology workers, options и overflow semantics нельзя автоматически -считать эквивалентными LogIt++. Boost.Log позволяет строить асинхронные pipeline -через sinks и backends, но имеет более общий configuration model. glog и -IceCream-Cpp не являются прямыми аналогами этой queue architecture. +считать эквивалентными LogIt++. Boost.Log предоставляет asynchronous sink +frontends, включая bounded FIFO queues со стратегиями drop-on-overflow и +block-on-overflow, через более общий sink configuration model. glog и IceCream-Cpp +не являются прямыми аналогами этой queue architecture. ## Structured data, storage и telemetry LogIt++ особенно уместен, когда log record нужен после самого вызова: - `MemoryLogger` поддерживает snapshots, readers и subscribers; -- file и MDBX backends могут сохранять structured records; +- `FileLogger` поддерживает перечисление сохранённых файлов и чтение их текста; +- `MdbxLogger` сохраняет structured records для последующих запросов; - OTLP exporters передают выбранные structured attributes и context; - Prometheus backends публикуют application и built-in metrics; - MDC/NDC, tags и argument values проходят через одну record model. Ближайший архитектурный аналог здесь — Boost.Log с его extensible records, -attributes, filters и sinks. spdlog и Quill обычно проще для formatted messages -и high-throughput sinks. glog сознательно сфокусирован на application diagnostics -и severity/check macros. Это trade-offs области применения, а не универсальный -рейтинг библиотек. +attributes, filters и sinks. spdlog обычно проще для formatted messages и +high-throughput sinks. Quill сочетает этот performance-фокус с named-value macros, +JSON output, tags и MDC в рамках собственной record model. glog сфокусирован на +application diagnostics и severity/check macros. Это trade-offs области +применения, а не универсальный рейтинг библиотек. ## Снимок производительности @@ -177,12 +185,20 @@ Harness пока не измеряет allocations на сообщение, bina backend-ов; - подходит header-only C++11 core с отдельными C++17 integrations. -**Рассмотрите spdlog или Quill, если:** +**Рассмотрите spdlog, если:** - главное — сфокусированный быстрый pipeline для formatted messages; -- подходят их sinks, queue design или ecosystem; +- подходят его sinks, async queue design или ecosystem; - хранить structured diagnostic records не требуется. +**Рассмотрите Quill, если:** + +- главное — asynchronous low-latency logging pipeline; +- его named-value macros, JSON output, tags, MDC и Prometheus metrics покрывают + требования к structured data; +- не нужны persistent structured storage, программный read-back и live + subscriptions в модели LogIt++. + **Рассмотрите Boost.Log, если:** - важнее общий framework attributes/filters/sinks, чем компактный macro facade; @@ -193,6 +209,11 @@ Harness пока не измеряет allocations на сообщение, bina - нужны прежде всего Google-style severity, check и diagnostic macros; - узкая application logging model предпочтительнее storage и telemetry backend-ов. +На момент проверки 10.09.2026 +[upstream-репозиторий `google/glog`](https://github.com/google/glog) был +архивирован и переведён в режим read-only. Учитывайте этот lifecycle-статус +перед добавлением glog как новой зависимости. + **Рассмотрите IceCream-Cpp, если:** - нужен лёгкий introspection исходных выражений во время разработки; diff --git a/docs/comparison.md b/docs/comparison.md index 8d7e071..36c6594 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -7,7 +7,7 @@ answers a practical question: **when does LogIt++ fit better than a smaller formatted-string logger, a general event framework, or a diagnostic macro utility?** -The comparison was checked on **2026-09-08** against these upstream releases: +The comparison was checked on **2026-09-10** against these upstream releases: | Project | Release checked | Primary documentation | | --- | --- | --- | @@ -45,18 +45,22 @@ goal of the checked project, not that it is impossible to implement. | Capability | LogIt++ | spdlog | Quill | Boost.Log | glog | IceCream-Cpp | | --- | --- | --- | --- | --- | --- | --- | -| Macro-first instrumentation | Built in | Built in macros | Built in macros | Different model | Built in macros | Core feature | -| Structured records / attributes | Built in `LogRecord` and values | Different model: formatted message and formatter arguments | Different model: typed async log messages | Built in attribute/event model | Extension / message-centric | Diagnostic values, not a sink record | -| Capture source argument names | Built in | — | — | — | — | Built in | -| `printf`-style and stream APIs | Built in | Built in | Built in / fmt-oriented | Extension / different model | Stream-oriented macros | Human-readable display | -| Conditional and rate-limited macros | Built in | Built in macro families | API-dependent | Filters and predicates | Built in severity/condition macros | Limited diagnostic helpers | -| Asynchronous queue | Built in | Built in | Core design | Sink-dependent | Not the primary model | — | -| Configurable overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Queue policies documented by Quill | Sink/configuration dependent | — | — | -| Rotating file sink | Built in | Built in | Built in handlers | Built in sink types | Basic file logging; rotation is a different concern | — | -| In-memory history and read-back | Built in for selected backends | Extension | Extension | Extension / custom sink | — | — | -| Live log subscriptions | Built in for selected backends | Extension | Extension | Extension | — | — | -| Persistent structured storage | Built in optional MDBX backend | Extension | Extension | Extension | — | — | -| OTLP and Prometheus integrations | Built in optional backends | Extension / adapter | Extension / adapter | Extension / adapter | Extension / adapter | — | +| Macro-first instrumentation | Built in | Built-in severity macros | Built in macros | Built-in macros over a record/stream model | Built in macros | Core feature | +| Structured records / attributes | Built in `LogRecord` and values | Formatted messages plus MDC (synchronous logging only); different record model | Built-in named-value logging, JSON output, tags, and MDC; different record model | Built in attribute/event model | Extension / message-centric | Diagnostic values, not a sink record | +| Capture source argument names | Built in | — | Built in via `LOGV_*` | — | — | Core feature | +| `{fmt}`-style formatting | Built in when `LOGIT_WITH_FMT=ON` | Built in | Built in | Extension / pre-formatting | Extension / pre-formatting | — | +| `printf`-style logging | Built in | Extension / pre-formatting | Extension / pre-formatting | Extension / pre-formatting | Built in via low-level `RAW_LOG` | — | +| Stream-style logging | Built in | Extension / pre-formatting | Extension / pre-formatting | Built in | Built in | Human-readable diagnostic output | +| Conditional logging helpers | Built in | No dedicated helper; use an application condition | No dedicated helper; use an application condition | Filters and predicates; no equivalent call-site macro | Built in via `LOG_IF` | Configuration helpers, not a logging framework | +| Rate-limited logging helpers | Built in | No dedicated macro family | Built in via `LOG_*_LIMIT` and `LOGV_*_LIMIT` | Extension / custom filter | Built in via `LOG_EVERY_N`, `LOG_FIRST_N`, and related macros | — | +| Asynchronous queue | Built in | Built in | Core design | Built in via asynchronous sink frontends | Not the primary model | — | +| Configurable overflow/backpressure | Built in (`Block`, `DropNewest`, `DropOldest`) | Built in overflow policies | Built-in bounded/unbounded and blocking/dropping queue modes | Built in via bounded async sink queue strategies (`drop_on_overflow`, `block_on_overflow`) | — | — | +| Rotating file sink | Built in | Built in | Built in via `RotatingFileSink` | Built in sink types | Built-in file rollover/cleanup; different model | — | +| In-memory history and read-back | Built in for selected backends | Built-in backtrace buffer; no equivalent read-back API | Built-in backtrace logging; no equivalent read-back API | Extension / custom sink | — | — | +| Live log subscriptions | Built in for selected backends | Built-in callback sink; different model | Extension / custom sink | Extension / custom sink | — | — | +| Embedded queryable structured storage | Built in via optional MDBX backend | Extension | Extension | Extension | — | — | +| OTLP / OpenTelemetry log export | Built in optional backend | Extension / adapter | Extension / custom sink | Extension / adapter | Extension / adapter | — | +| Prometheus metrics | Built in optional backends | Extension / adapter | Built in via `PrometheusSink` | Extension / adapter | Extension / adapter | — | | Header-only integration | Built in | Supported mode | CMake/library integration | Compiled Boost component | CMake/library integration | Header-oriented utility | The word “built in” is intentionally narrow. For example, all of these @@ -85,10 +89,10 @@ also does more work than a minimal formatted-string call. spdlog, Quill, and glog also provide useful macro families, but their primary abstractions remain logger calls, formatted messages, or severity/check -macros. Boost.Log emphasizes records, attributes, filters, and sinks rather -than a single macro facade. IceCream-Cpp is the closest comparison for -argument-name display, but it deliberately stops short of being a logger -backend framework. +macros. Boost.Log provides logging macros over its record, attribute, filter, +and sink model rather than a single broad macro facade. IceCream-Cpp is the +closest comparison as a dedicated introspection utility; Quill also captures +source variable names through its `LOGV_*` logging macros. ## Why IceCream-Cpp is a different comparison @@ -117,25 +121,29 @@ accepted work. spdlog and Quill are closer comparisons for asynchronous throughput and queue configuration. Their options, worker topology, and overflow semantics are not interchangeable with LogIt++, so a benchmark must hold the workload and -delivery contract constant. Boost.Log can express asynchronous pipelines -through sinks and backends, but its configuration model is more general. glog -and IceCream-Cpp are not primary comparisons for this queue design. +delivery contract constant. Boost.Log provides asynchronous sink frontends, +including bounded FIFO queues with drop-on-overflow and block-on-overflow +strategies, through a more general sink configuration model. glog and +IceCream-Cpp are not primary comparisons for this queue design. ## Structured data, storage, and telemetry Choose LogIt++ when the log record itself is useful after the logging call: - `MemoryLogger` supports snapshots, readers, and subscribers; -- file and MDBX backends can retain structured records for later access; +- `FileLogger` supports persisted-file enumeration and text read-back; +- `MdbxLogger` retains structured records for later querying; - OTLP exporters preserve selected structured attributes and context; - Prometheus backends expose application and built-in metrics; - MDC/NDC, tags, and argument values can flow through the same record model. Boost.Log is the closest architectural comparison for an extensible record, -attribute, filter, and sink pipeline. spdlog and Quill are usually simpler to -adopt for formatted messages and high-throughput sinks. glog is intentionally -focused on application diagnostics and severity/check macros. These are -trade-offs in scope, not a claim that one design is universally better. +attribute, filter, and sink pipeline. spdlog is usually simpler to adopt for +formatted messages and high-throughput sinks. Quill combines that performance +focus with named-value macros, JSON output, tags, and MDC through its own +record model. glog is focused on application diagnostics and severity/check +macros. These are trade-offs in scope, not a claim that one design is +universally better. ## Performance snapshot @@ -190,12 +198,20 @@ Choose LogIt++ with its trade-offs in mind: delivery behavior matter; - a header-only C++11 core with optional C++17 integrations fits the project. -**Consider spdlog or Quill when:** +**Consider spdlog when:** - the main requirement is a focused, fast formatted-message pipeline; -- their existing sinks, queue design, or ecosystem match the application; +- its existing sinks, async queue design, or ecosystem match the application; - retaining structured diagnostic records is not necessary. +**Consider Quill when:** + +- an asynchronous, low-latency logging pipeline is the main requirement; +- its named-value macros, JSON output, tags, MDC, and Prometheus metrics fit + the structured-data requirements; +- LogIt++-style persistent structured storage, programmatic read-back, and + live subscriptions are not required. + **Consider Boost.Log when:** - a general attribute/filter/sink framework is more important than a compact @@ -208,6 +224,10 @@ Choose LogIt++ with its trade-offs in mind: - a narrower application logging model is preferable to storage and telemetry backends. +The [upstream `google/glog` repository](https://github.com/google/glog) was +archived and made read-only as of the 2026-09-10 check; account for that +lifecycle status before adopting it as a new dependency. + **Consider IceCream-Cpp when:** - the goal is lightweight source-expression introspection during development; From 05a315b445d21b58d7f81d737291a2090d6217d1 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Fri, 11 Sep 2026 01:16:27 +0300 Subject: [PATCH 6/6] docs: qualify glog raw logging Clarify that glog's printf-style RAW_LOG API is limited to low-level stderr logging in both comparison translations. --- docs/comparison-RU.md | 2 +- docs/comparison.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/comparison-RU.md b/docs/comparison-RU.md index 436c9bb..b8b8dd7 100644 --- a/docs/comparison-RU.md +++ b/docs/comparison-RU.md @@ -48,7 +48,7 @@ API покрывает условное логирование, throttling, scop | Structured records / attributes | Built in `LogRecord` и values | Formatted messages и MDC (только synchronous logging); другая record model | Встроенные named-value logging, JSON output, tags и MDC; другая record model | Built in attributes/events | Extension / message-centric | Диагностические values, не sink record | | Захват имён аргументов | Built in | — | Built in через `LOGV_*` | — | — | Основная функция | | Форматирование в стиле `{fmt}` | Built in при `LOGIT_WITH_FMT=ON` | Built in | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | — | -| Логирование в стиле `printf` | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | Extension / предварительное форматирование | Built in через низкоуровневый `RAW_LOG` | — | +| Логирование в стиле `printf` | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | Extension / предварительное форматирование | Только низкоуровневый `RAW_LOG` (только stderr) | — | | Логирование в стиле stream | Built in | Extension / предварительное форматирование | Extension / предварительное форматирование | Built in | Built in | Диагностический вывод, не stream API | | Условное логирование | Built in | Нет специального helper-а; используется условие приложения | Нет специального helper-а; используется условие приложения | Filters и predicates; нет аналогичного call-site macro | Built in через `LOG_IF` | Configuration helpers, не logging framework | | Rate-limited logging | Built in | Нет специального семейства macros | Built in через `LOG_*_LIMIT` и `LOGV_*_LIMIT` | Extension / custom filter | Built in через `LOG_EVERY_N`, `LOG_FIRST_N` и связанные macros | — | diff --git a/docs/comparison.md b/docs/comparison.md index 36c6594..133b82f 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -49,7 +49,7 @@ goal of the checked project, not that it is impossible to implement. | Structured records / attributes | Built in `LogRecord` and values | Formatted messages plus MDC (synchronous logging only); different record model | Built-in named-value logging, JSON output, tags, and MDC; different record model | Built in attribute/event model | Extension / message-centric | Diagnostic values, not a sink record | | Capture source argument names | Built in | — | Built in via `LOGV_*` | — | — | Core feature | | `{fmt}`-style formatting | Built in when `LOGIT_WITH_FMT=ON` | Built in | Built in | Extension / pre-formatting | Extension / pre-formatting | — | -| `printf`-style logging | Built in | Extension / pre-formatting | Extension / pre-formatting | Extension / pre-formatting | Built in via low-level `RAW_LOG` | — | +| `printf`-style logging | Built in | Extension / pre-formatting | Extension / pre-formatting | Extension / pre-formatting | Low-level `RAW_LOG` only (stderr-only) | — | | Stream-style logging | Built in | Extension / pre-formatting | Extension / pre-formatting | Built in | Built in | Human-readable diagnostic output | | Conditional logging helpers | Built in | No dedicated helper; use an application condition | No dedicated helper; use an application condition | Filters and predicates; no equivalent call-site macro | Built in via `LOG_IF` | Configuration helpers, not a logging framework | | Rate-limited logging helpers | Built in | No dedicated macro family | Built in via `LOG_*_LIMIT` and `LOGV_*_LIMIT` | Extension / custom filter | Built in via `LOG_EVERY_N`, `LOG_FIRST_N`, and related macros | — |