From 38ac31ed9434af97bf1ae49bda19fad1b2d04481 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Mon, 15 Sep 2025 07:32:56 +0300 Subject: [PATCH 1/4] docs(readme): expand macro reference --- README-RU.md | 30 +++++++++++++++++++++++++++++- README.md | 24 +++++++++++++++++++++--- 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/README-RU.md b/README-RU.md index 30d3d1a..99c70ad 100644 --- a/README-RU.md +++ b/README-RU.md @@ -39,7 +39,23 @@ auto now = std::chrono::system_clock::now(); LOGIT_PRINT_INFO("TimePoint example: ", now); ``` -- **Поддержка нескольких бэкендов**: +- **Фильтры и ограничение частоты логов**: + +Сократите шум от повторяющихся сообщений с помощью макросов `LOGIT_WARN_ONCE`, +`LOGIT_INFO_EVERY_N` и `LOGIT_ERROR_THROTTLE`. Макросы с суффиксом +`_THROTTLE` (например, `LOGIT_INFO_THROTTLE`) ограничивают вывод одним +сообщением за заданный промежуток времени. + +```cpp +for (int i = 0; i < 10; ++i) { + LOGIT_WARN_ONCE("initializing"); // выводится один раз + LOGIT_INFO_EVERY_N(3, "heartbeat", i); // каждое 3-е сообщение + LOGIT_ERROR_THROTTLE(200, "repeated error"); // не чаще 1 раза/200 мс + std::this_thread::sleep_for(std::chrono::milliseconds(50)); +} +``` + +- **Поддержка нескольких бэкендов**: Легко настройте логгеры для вывода в консоль и файлы. При необходимости добавьте отправку сообщений на сервер или в базу данных, создавая собственные бэкенды. @@ -88,6 +104,18 @@ public: LOGIT_ADD_LOGGER(CustomLogger, (), logit::SimpleLogFormatter, ("%v")); ``` +## Справочник макросов + +| Шаблон макроса | Описание | +| --------------- | -------- | +| `LOGIT_(...)` | Логирование с указанным уровнем (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). | +| `LOGIT_PRINT_(...)` | Логирование заранее сформированной строки или сообщения, собранного через потоки. | +| `LOGIT__IF(condition, ...)` | Логирование только если условие истинно. | +| `LOGIT__ONCE(...)` | Логирование только при первом вызове. | +| `LOGIT__EVERY_N(n, ...)` | Логирование каждого `n`-го вызова. | +| `LOGIT__THROTTLE(period_ms, ...)` | Логирование не чаще одного раза за `period_ms` миллисекунд. | +| `LOGIT__TAG(({{"k", "v"}}), msg)` | Добавление к сообщению пар ключ-значение. | + --- ## Использование diff --git a/README.md b/README.md index f94acc7..2a0e23f 100644 --- a/README.md +++ b/README.md @@ -53,11 +53,17 @@ LOGIT_PRINT_INFO("TimePoint example: ", now); - **Log Filters and Throttling**: -Reduce noise from repetitive messages with macros like `LOGIT_WARN_ONCE`, `LOGIT_INFO_EVERY_N`, and `LOGIT_ERROR_THROTTLE`. +Reduce noise from repetitive messages with macros like `LOGIT_WARN_ONCE`, +`LOGIT_INFO_EVERY_N`, and `LOGIT_ERROR_THROTTLE`. Use the `_THROTTLE` +variants (e.g., `LOGIT_INFO_THROTTLE`) to limit output to one message per +time period. ```cpp -for (int i = 0; i < 1000; ++i) { - LOGIT_INFO_EVERY_N(100, "heartbeat"); +for (int i = 0; i < 10; ++i) { + LOGIT_WARN_ONCE("initializing"); // prints once + LOGIT_INFO_EVERY_N(3, "heartbeat", i); // every 3rd call + LOGIT_ERROR_THROTTLE(200, "repeated error"); // max once/200ms + std::this_thread::sleep_for(std::chrono::milliseconds(50)); } ``` @@ -498,6 +504,18 @@ public: }; ``` +## Macro Reference + +| Macro pattern | Description | +| ------------- | ----------- | +| `LOGIT_(...)` | Log a message with the given level (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). | +| `LOGIT_PRINT_(...)` | Log a pre-formatted string or stream-built message. | +| `LOGIT__IF(condition, ...)` | Log only when `condition` is true. | +| `LOGIT__ONCE(...)` | Log only the first time the macro is executed. | +| `LOGIT__EVERY_N(n, ...)` | Log on every `n`th invocation. | +| `LOGIT__THROTTLE(period_ms, ...)` | Log at most once per `period_ms` milliseconds. | +| `LOGIT__TAG(({{"k", "v"}}), msg)` | Attach key-value tags to a message. | + --- ## Installation From 2f95b5fc5d8adc1144651e95a02c3723ac92ebd8 Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Mon, 15 Sep 2025 07:48:23 +0300 Subject: [PATCH 2/4] docs: document format macros --- README-RU.md | 6 ++++-- README.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README-RU.md b/README-RU.md index 99c70ad..49e2450 100644 --- a/README-RU.md +++ b/README-RU.md @@ -28,8 +28,8 @@ try { - **Логирование с использованием макросов**: -Легко логируйте переменные и сообщения с помощью макросов. Просто выберите подходящий макрос и передайте переменные или аргументы. - +Легко логируйте переменные и сообщения с помощью макросов. Просто выберите подходящий макрос и передайте переменные или аргументы. Для printf-подобного форматирования используйте `LOGIT_FORMAT_`. + ``` float someFloat = 123.456f; int someInt = 789; @@ -37,6 +37,7 @@ LOGIT_INFO(someFloat, someInt); auto now = std::chrono::system_clock::now(); LOGIT_PRINT_INFO("TimePoint example: ", now); +LOGIT_FORMAT_INFO("%s: %d", "status", 200); // printf-подобное форматирование ``` - **Фильтры и ограничение частоты логов**: @@ -110,6 +111,7 @@ LOGIT_ADD_LOGGER(CustomLogger, (), logit::SimpleLogFormatter, ("%v")); | --------------- | -------- | | `LOGIT_(...)` | Логирование с указанным уровнем (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). | | `LOGIT_PRINT_(...)` | Логирование заранее сформированной строки или сообщения, собранного через потоки. | +| `LOGIT_FORMAT_(fmt, ...)` | printf-подобное форматирование с форматной строкой и аргументами. | | `LOGIT__IF(condition, ...)` | Логирование только если условие истинно. | | `LOGIT__ONCE(...)` | Логирование только при первом вызове. | | `LOGIT__EVERY_N(n, ...)` | Логирование каждого `n`-го вызова. | diff --git a/README.md b/README.md index 2a0e23f..427d271 100644 --- a/README.md +++ b/README.md @@ -38,9 +38,9 @@ try { > 23:59:59.128 | An example runtime error ``` -- **Macro-Based Logging**: + - **Macro-Based Logging**: -Easily log variables and messages using macros. Simply choose the appropriate macro and pass variables or arguments to it. +Easily log variables and messages using macros. Simply choose the appropriate macro and pass variables or arguments to it. Use `LOGIT_FORMAT_` for printf-style formatting. ``` float someFloat = 123.456f; @@ -49,6 +49,7 @@ LOGIT_INFO(someFloat, someInt); auto now = std::chrono::system_clock::now(); LOGIT_PRINT_INFO("TimePoint example: ", now); +LOGIT_FORMAT_INFO("%s: %d", "status", 200); // printf-style ``` - **Log Filters and Throttling**: @@ -510,6 +511,7 @@ public: | ------------- | ----------- | | `LOGIT_(...)` | Log a message with the given level (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). | | `LOGIT_PRINT_(...)` | Log a pre-formatted string or stream-built message. | +| `LOGIT_FORMAT_(fmt, ...)` | printf-style formatting with a format string and arguments. | | `LOGIT__IF(condition, ...)` | Log only when `condition` is true. | | `LOGIT__ONCE(...)` | Log only the first time the macro is executed. | | `LOGIT__EVERY_N(n, ...)` | Log on every `n`th invocation. | From 673f05f8e3a8277722903cfe769d88d60a60f5ae Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Mon, 15 Sep 2025 07:48:27 +0300 Subject: [PATCH 3/4] docs: add config and management macro tables --- README-RU.md | 23 +++++++++++++++++++++++ README.md | 23 +++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/README-RU.md b/README-RU.md index 49e2450..f194768 100644 --- a/README-RU.md +++ b/README-RU.md @@ -118,6 +118,29 @@ LOGIT_ADD_LOGGER(CustomLogger, (), logit::SimpleLogFormatter, ("%v")); | `LOGIT__THROTTLE(period_ms, ...)` | Логирование не чаще одного раза за `period_ms` миллисекунд. | | `LOGIT__TAG(({{"k", "v"}}), msg)` | Добавление к сообщению пар ключ-значение. | +### Макросы конфигурации + +| Макрос | Описание | +| ------ | -------- | +| `LOGIT_BASE_PATH` | Базовый путь, который обрезается из `__FILE__` в сообщениях. | +| `LOGIT_DEFAULT_COLOR` | Цвет вывода в консоль по умолчанию. | +| `LOGIT_COLOR_` | Цвет для каждого уровня логирования. | +| `LOGIT_CONSOLE_PATTERN` | Паттерн форматирования вывода в консоль по умолчанию. | +| `LOGIT_FILE_LOGGER_PATH` | Каталог для файловых логов. | +| `LOGIT_UNIQUE_FILE_LOGGER_PATH` | Каталог для логов по одному сообщению в файл. | +| `LOGIT_TAGS_JOIN` | Разделитель между сообщением и списком тегов. | + +### Функциональные макросы + +| Макрос | Описание | +| ------ | -------- | +| `LOGIT_SET_MAX_QUEUE(size)` | Устанавливает размер очереди задач (0 — без ограничений). | +| `LOGIT_SET_QUEUE_POLICY(mode)` | Поведение при переполнении: `LOGIT_QUEUE_DROP_NEWEST`, `LOGIT_QUEUE_DROP_OLDEST` или `LOGIT_QUEUE_BLOCK`. | +| `LOGIT_SET_LOG_LEVEL_TO(index, level)` | Задает минимальный уровень для конкретного логгера. | +| `LOGIT_SET_LOG_LEVEL(level)` | Задает минимальный уровень для всех логгеров. | +| `LOGIT_SET_TIME_OFFSET(index, offset_ms)` | Сдвигает временную метку логгера. | +| `LOGIT_GET_INT_PARAM(index, param)` | Получает целочисленный параметр логгера. | + --- ## Использование diff --git a/README.md b/README.md index 427d271..3f584f4 100644 --- a/README.md +++ b/README.md @@ -518,6 +518,29 @@ public: | `LOGIT__THROTTLE(period_ms, ...)` | Log at most once per `period_ms` milliseconds. | | `LOGIT__TAG(({{"k", "v"}}), msg)` | Attach key-value tags to a message. | +### Configuration Macros + +| Macro | Description | +| ----- | ----------- | +| `LOGIT_BASE_PATH` | Trim this prefix from `__FILE__` paths shown in logs. | +| `LOGIT_DEFAULT_COLOR` | Default console color for messages. | +| `LOGIT_COLOR_` | Color for each log level. | +| `LOGIT_CONSOLE_PATTERN` | Default format pattern for console output. | +| `LOGIT_FILE_LOGGER_PATH` | Directory for rotating file logs. | +| `LOGIT_UNIQUE_FILE_LOGGER_PATH` | Directory for one-message-per-file logs. | +| `LOGIT_TAGS_JOIN` | Separator inserted between the message and tag list. | + +### Management Macros + +| Macro | Description | +| ----- | ----------- | +| `LOGIT_SET_MAX_QUEUE(size)` | Limit the asynchronous task queue (0 for unlimited). | +| `LOGIT_SET_QUEUE_POLICY(mode)` | Set overflow behavior: `LOGIT_QUEUE_DROP_NEWEST`, `LOGIT_QUEUE_DROP_OLDEST`, or `LOGIT_QUEUE_BLOCK`. | +| `LOGIT_SET_LOG_LEVEL_TO(index, level)` | Set minimum log level for a specific logger. | +| `LOGIT_SET_LOG_LEVEL(level)` | Set minimum log level for all loggers. | +| `LOGIT_SET_TIME_OFFSET(index, offset_ms)` | Adjust timestamp offset for a logger. | +| `LOGIT_GET_INT_PARAM(index, param)` | Retrieve an integer parameter from a logger. | + --- ## Installation From 19b90e0cd91ec99a7d62b40f5403e99efe9e09ed Mon Sep 17 00:00:00 2001 From: Aster Seker Date: Mon, 15 Sep 2025 07:54:19 +0300 Subject: [PATCH 4/4] docs(readme): document additional macros --- README-RU.md | 13 +++++++++++++ README.md | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/README-RU.md b/README-RU.md index f194768..b01c387 100644 --- a/README-RU.md +++ b/README-RU.md @@ -112,6 +112,7 @@ LOGIT_ADD_LOGGER(CustomLogger, (), logit::SimpleLogFormatter, ("%v")); | `LOGIT_(...)` | Логирование с указанным уровнем (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). | | `LOGIT_PRINT_(...)` | Логирование заранее сформированной строки или сообщения, собранного через потоки. | | `LOGIT_FORMAT_(fmt, ...)` | printf-подобное форматирование с форматной строкой и аргументами. | +| `LOGIT_STREAM_()` | Потоковое логирование через `<<`; короткие версии `LOG_S_()` доступны при определении `LOGIT_SHORT_NAME`. | | `LOGIT__IF(condition, ...)` | Логирование только если условие истинно. | | `LOGIT__ONCE(...)` | Логирование только при первом вызове. | | `LOGIT__EVERY_N(n, ...)` | Логирование каждого `n`-го вызова. | @@ -138,8 +139,20 @@ LOGIT_ADD_LOGGER(CustomLogger, (), logit::SimpleLogFormatter, ("%v")); | `LOGIT_SET_QUEUE_POLICY(mode)` | Поведение при переполнении: `LOGIT_QUEUE_DROP_NEWEST`, `LOGIT_QUEUE_DROP_OLDEST` или `LOGIT_QUEUE_BLOCK`. | | `LOGIT_SET_LOG_LEVEL_TO(index, level)` | Задает минимальный уровень для конкретного логгера. | | `LOGIT_SET_LOG_LEVEL(level)` | Задает минимальный уровень для всех логгеров. | +| `LOGIT_SET_LOGGER_ENABLED(index, enabled)` | Включает или отключает логгер. | +| `LOGIT_IS_LOGGER_ENABLED(index)` | Проверяет, включен ли логгер. | +| `LOGIT_SET_SINGLE_MODE(index, single_mode)` | Включает режим «один файл — одно сообщение». | +| `LOGIT_IS_SINGLE_MODE(index)` | Проверяет, активен ли режим «один файл — одно сообщение». | | `LOGIT_SET_TIME_OFFSET(index, offset_ms)` | Сдвигает временную метку логгера. | +| `LOGIT_GET_STRING_PARAM(index, param)` | Получает строковый параметр логгера. | | `LOGIT_GET_INT_PARAM(index, param)` | Получает целочисленный параметр логгера. | +| `LOGIT_GET_FLOAT_PARAM(index, param)` | Получает параметр с плавающей точкой. | +| `LOGIT_GET_LAST_FILE_NAME(index)` | Имя последнего файла, в который писал логгер. | +| `LOGIT_GET_LAST_FILE_PATH(index)` | Путь к последнему файлу логгера. | +| `LOGIT_GET_LAST_LOG_TIMESTAMP(index)` | Метка времени последнего лога. | +| `LOGIT_GET_TIME_SINCE_LAST_LOG(index)` | Время с последнего лога (в секундах). | +| `LOGIT_WAIT()` | Ожидает завершения всех асинхронных логгеров. | +| `LOGIT_SHUTDOWN()` | Завершает работу системы логирования. | --- diff --git a/README.md b/README.md index 3f584f4..73e01f5 100644 --- a/README.md +++ b/README.md @@ -512,6 +512,7 @@ public: | `LOGIT_(...)` | Log a message with the given level (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). | | `LOGIT_PRINT_(...)` | Log a pre-formatted string or stream-built message. | | `LOGIT_FORMAT_(fmt, ...)` | printf-style formatting with a format string and arguments. | +| `LOGIT_STREAM_()` | Stream-style logging with `<<` operators; short aliases `LOG_S_()` when `LOGIT_SHORT_NAME` is defined. | | `LOGIT__IF(condition, ...)` | Log only when `condition` is true. | | `LOGIT__ONCE(...)` | Log only the first time the macro is executed. | | `LOGIT__EVERY_N(n, ...)` | Log on every `n`th invocation. | @@ -538,8 +539,20 @@ public: | `LOGIT_SET_QUEUE_POLICY(mode)` | Set overflow behavior: `LOGIT_QUEUE_DROP_NEWEST`, `LOGIT_QUEUE_DROP_OLDEST`, or `LOGIT_QUEUE_BLOCK`. | | `LOGIT_SET_LOG_LEVEL_TO(index, level)` | Set minimum log level for a specific logger. | | `LOGIT_SET_LOG_LEVEL(level)` | Set minimum log level for all loggers. | +| `LOGIT_SET_LOGGER_ENABLED(index, enabled)` | Enable or disable a logger. | +| `LOGIT_IS_LOGGER_ENABLED(index)` | Check whether a logger is enabled. | +| `LOGIT_SET_SINGLE_MODE(index, single_mode)` | Toggle single-message-per-file mode for a logger. | +| `LOGIT_IS_SINGLE_MODE(index)` | Determine if a logger is in single mode. | | `LOGIT_SET_TIME_OFFSET(index, offset_ms)` | Adjust timestamp offset for a logger. | +| `LOGIT_GET_STRING_PARAM(index, param)` | Retrieve a string parameter from a logger. | | `LOGIT_GET_INT_PARAM(index, param)` | Retrieve an integer parameter from a logger. | +| `LOGIT_GET_FLOAT_PARAM(index, param)` | Retrieve a floating-point parameter from a logger. | +| `LOGIT_GET_LAST_FILE_NAME(index)` | Get the last file name written by a logger. | +| `LOGIT_GET_LAST_FILE_PATH(index)` | Get the last file path written by a logger. | +| `LOGIT_GET_LAST_LOG_TIMESTAMP(index)` | Get the timestamp of the last log entry. | +| `LOGIT_GET_TIME_SINCE_LAST_LOG(index)` | Seconds elapsed since the last log entry. | +| `LOGIT_WAIT()` | Wait for all asynchronous loggers to finish. | +| `LOGIT_SHUTDOWN()` | Shut down the logging system. | ---