LimiNode · LimiNode · Sep 15, 2025 · Sep 15, 2025 · Sep 15, 2025 · Sep 15, 2025
diff --git a/README-RU.md b/README-RU.md
@@ -28,18 +28,35 @@ try {
 
 - **Логирование с использованием макросов**: 
 
-Легко логируйте переменные и сообщения с помощью макросов. Просто выберите подходящий макрос и передайте переменные или аргументы.
-	
+Легко логируйте переменные и сообщения с помощью макросов. Просто выберите подходящий макрос и передайте переменные или аргументы. Для printf-подобного форматирования используйте `LOGIT_FORMAT_<LEVEL>`.
+
 ```
 float someFloat = 123.456f;
 int someInt = 789;
 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-подобное форматирование
 ```
 
-- **Поддержка нескольких бэкендов**: 
+- **Фильтры и ограничение частоты логов**:
+
+Сократите шум от повторяющихся сообщений с помощью макросов `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 +105,55 @@ public:
 LOGIT_ADD_LOGGER(CustomLogger, (), logit::SimpleLogFormatter, ("%v"));
 ```
 
+## Справочник макросов
+
+| Шаблон макроса | Описание |
+| --------------- | -------- |
+| `LOGIT_<LEVEL>(...)` | Логирование с указанным уровнем (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). |
+| `LOGIT_PRINT_<LEVEL>(...)` | Логирование заранее сформированной строки или сообщения, собранного через потоки. |
+| `LOGIT_FORMAT_<LEVEL>(fmt, ...)` | printf-подобное форматирование с форматной строкой и аргументами. |
+| `LOGIT_STREAM_<LEVEL>()` | Потоковое логирование через `<<`; короткие версии `LOG_S_<LEVEL>()` доступны при определении `LOGIT_SHORT_NAME`. |
+| `LOGIT_<LEVEL>_IF(condition, ...)` | Логирование только если условие истинно. |
+| `LOGIT_<LEVEL>_ONCE(...)` | Логирование только при первом вызове. |
+| `LOGIT_<LEVEL>_EVERY_N(n, ...)` | Логирование каждого `n`-го вызова. |
+| `LOGIT_<LEVEL>_THROTTLE(period_ms, ...)` | Логирование не чаще одного раза за `period_ms` миллисекунд. |
+| `LOGIT_<LEVEL>_TAG(({{"k", "v"}}), msg)` | Добавление к сообщению пар ключ-значение. |
+
+### Макросы конфигурации
+
+| Макрос | Описание |
+| ------ | -------- |
+| `LOGIT_BASE_PATH` | Базовый путь, который обрезается из `__FILE__` в сообщениях. |
+| `LOGIT_DEFAULT_COLOR` | Цвет вывода в консоль по умолчанию. |
+| `LOGIT_COLOR_<LEVEL>` | Цвет для каждого уровня логирования. |
+| `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_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
@@ -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_<LEVEL>` for printf-style formatting.
 
 ```
 float someFloat = 123.456f;
@@ -49,15 +49,22 @@ 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**:
 
-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 +505,55 @@ public:
 };
 ```
 
+## Macro Reference
+
+| Macro pattern | Description |
+| ------------- | ----------- |
+| `LOGIT_<LEVEL>(...)` | Log a message with the given level (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`). |
+| `LOGIT_PRINT_<LEVEL>(...)` | Log a pre-formatted string or stream-built message. |
+| `LOGIT_FORMAT_<LEVEL>(fmt, ...)` | printf-style formatting with a format string and arguments. |
+| `LOGIT_STREAM_<LEVEL>()` | Stream-style logging with `<<` operators; short aliases `LOG_S_<LEVEL>()` when `LOGIT_SHORT_NAME` is defined. |
+| `LOGIT_<LEVEL>_IF(condition, ...)` | Log only when `condition` is true. |
+| `LOGIT_<LEVEL>_ONCE(...)` | Log only the first time the macro is executed. |
+| `LOGIT_<LEVEL>_EVERY_N(n, ...)` | Log on every `n`th invocation. |
+| `LOGIT_<LEVEL>_THROTTLE(period_ms, ...)` | Log at most once per `period_ms` milliseconds. |
+| `LOGIT_<LEVEL>_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_<LEVEL>` | 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_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. |
+
 ---
 
 ## Installation