doc: added wiki
This commit is contained in:
aZholtikov committed
1 parent
cb65332eb4
commit
d3d3817ae2
1 file changed
+214
+214
@@ -0,0 +1,214 @@
|
||||
# Описание компонента zh_syslog
|
||||
|
||||
## Общие сведения
|
||||
|
||||
**zh_syslog** — это лёгкий UDP-клиент syslog для ESP-IDF, отправляющий сообщения на удалённый syslog-сервер в формате [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424).
|
||||
|
||||
Компонент оборачивает стандартный BSD-сокет UDP и предоставляет несколько функций для инициализации, отправки сообщений и освобождения ресурсов.
|
||||
|
||||
## Основные возможности
|
||||
|
||||
1. **Все коды facility (0–23)** — поддержка стандартных значений по RFC 5424, включая `LOCAL0`–`LOCAL7` для локального использования.
|
||||
2. **Все уровни severity (0–7)** — от `ZH_EMERG` до `ZH_DEBUG`.
|
||||
3. **Формат RFC 5424** — автоматический расчёт приоритета `<PRI>` и генерация заголовка сообщения.
|
||||
4. **Отправка по UDP** — сокеты не устанавливают соединения, сообщения доставляются дейтаграммами.
|
||||
5. **Двухуровневая работа с памятью** — короткие сообщения форматируются в стековом буфере, длинные аллоцируются в куче точным размером.
|
||||
6. **Проверка входных аргументов** — валидация IP-адреса, порта и диапазона кодов на этапе вызова.
|
||||
7. **Потокобезопасные `init`/`deinit`** — защита состояния флагом инициализации (см. раздел «Ограничения» для `send`).
|
||||
|
||||
## Внутреннее устройство
|
||||
|
||||
### Структура `zh_syslog_init_config_t`
|
||||
|
||||
Публичная конфигурационная структура, передаваемая в `zh_syslog_init()`.
|
||||
|
||||
| Поле | Тип | Описание |
|
||||
|------|-----|----------|
|
||||
| `syslog_ip` | `char[16]` | IPv4-адрес syslog-сервера в виде строки (макс. 15 символов + `'\0'`) |
|
||||
| `syslog_port` | `uint32_t` | UDP-порт сервера (диапазон 1–65535, по умолчанию 514) |
|
||||
|
||||
Для заполнения значений по умолчанию используется макрос `ZH_SYSLOG_INIT_CONFIG_DEFAULT()` (IP `192.168.0.1`, порт `514`).
|
||||
|
||||
### Внутренние переменные модуля
|
||||
|
||||
Не входят в публичный API и хранятся как `static` в `zh_syslog.c`.
|
||||
|
||||
| Переменная | Тип | Описание |
|
||||
|------------|-----|----------|
|
||||
| `_syslog_server` | `struct sockaddr_in` | Адрес сервера: IPv4, порт в сетевом порядке, семья `AF_INET` |
|
||||
| `_socket` | `volatile int` | Дескриптор UDP-сокета, `-1` когда клиент не инициализирован |
|
||||
| `_is_initialized` | `volatile bool` | Флаг состояния: `true` после успешного `init` |
|
||||
|
||||
Флаг `_is_initialized` используется как простой сторож состояния: `init` отказывает при уже инициализированном клиенте, `deinit` и `send` отказывают при неинициализированном.
|
||||
|
||||
### Управление памятью
|
||||
|
||||
- Короткое сообщение (помещающееся в стековый буфер `char stack_buf[256]`) форматируется прямо в стеке — аллокации в куче не происходит.
|
||||
- Если `snprintf` вернул `len >= 256` (строка обрезана), память выделяется в куче ровно под `len + 1` байт через `heap_caps_calloc(..., MALLOC_CAP_8BIT)`.
|
||||
- Флаг `heap_allocated` отслеживает, нужно ли освобождать буфер: `heap_caps_free()` вызывается владением только для кучного буфера — и при успехе, и при ошибке форматирования.
|
||||
|
||||
## API (интерфейс)
|
||||
|
||||
### Инициализация и освобождение
|
||||
|
||||
| Функция | Описание |
|
||||
|---------|----------|
|
||||
| `zh_syslog_init()` | Создаёт UDP-сокет и настраивает параметры соединения с сервером. |
|
||||
| `zh_syslog_deinit()` | Закрывает сокет и сбрасывает состояние клиента. |
|
||||
|
||||
### Отправка сообщений
|
||||
|
||||
| Функция | Описание |
|
||||
|---------|----------|
|
||||
| `zh_syslog_send()` | Форматирует сообщение по RFC 5424 и отправляет его на настроенный сервер. |
|
||||
|
||||
### Типы и значения
|
||||
|
||||
| Элемент | Описание |
|
||||
|---------|----------|
|
||||
| `zh_syslog_facility_code_t` | Перечисление кодов facility `ZH_KERN`…`ZH_LOCAL7` (0–23). |
|
||||
| `zh_syslog_severity_code_t` | Перечисление уровней severity `ZH_EMERG`…`ZH_DEBUG` (0–7). |
|
||||
| `zh_syslog_init_config_t` | Структура конфигурации (IP и порт сервера). |
|
||||
| `ZH_SYSLOG_INIT_CONFIG_DEFAULT()` | Макрос значений конфигурации по умолчанию. |
|
||||
|
||||
## Потокобезопасность
|
||||
|
||||
1. **Флаг состояния `_is_initialized`** — `volatile bool`, используется как сторож в `init`/`deinit`/`send` для защиты от повторной инициализации и от работы без инициализации.
|
||||
2. **Дескриптор сокета `_socket`** — `volatile int`, обновляется при `init`/`deinit`.
|
||||
|
||||
Мьютексы и критические секции не используются. Проверка флага и последующая работа с сокетом не образуют атомарной операции, поэтому `zh_syslog_send()` **не является потокобезопасной** — подробности в разделе «Ограничения».
|
||||
|
||||
## Алгоритмы
|
||||
|
||||
### Расчёт приоритета
|
||||
|
||||
- Приоритет `<PRI>` считается по формуле RFC 5424: `pri = facility * 8 + severity`.
|
||||
- Значение подставляется в начало сообщения в угловых скобках: `<%d>1 - ...`.
|
||||
|
||||
### Формат сообщения
|
||||
|
||||
Шаблон генерируемого сообщения:
|
||||
|
||||
```
|
||||
<PRI>1 - HOSTNAME APP-NAME - - - MESSAGE
|
||||
```
|
||||
|
||||
Поля `PROCID`, `MSGID` и `STRUCTURED-DATA` не заполняются и заменяются на `-` согласно RFC 5424.
|
||||
|
||||
### Выбор буфера под размер сообщения
|
||||
|
||||
- Сообщение форматируется в стековый буфер `stack_buf[256]` через `snprintf`, который возвращает полную длину строки.
|
||||
- Если возвращённая длина меньше размера буфера — сокету передаётся стековый буфер.
|
||||
- Если длина `>= 256` — выделяется кучный буфер точного размера `len + 1`, сообщение форматируется повторно и отправляется, после чего буфер освобождается.
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Базовый пример
|
||||
|
||||
```c
|
||||
#include "zh_syslog.h"
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
// Сеть (Wi-Fi/Ethernet) должна быть поднята до init
|
||||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||||
strcpy(config.syslog_ip, "192.168.1.100");
|
||||
config.syslog_port = 514;
|
||||
|
||||
if (zh_syslog_init(&config) == ESP_OK)
|
||||
{
|
||||
// Отправка сообщения с приоритетом USER/INFO
|
||||
zh_syslog_send(ZH_USER, ZH_INFO, "esp32_node", "my_app", "Hello syslog");
|
||||
}
|
||||
|
||||
// Освобождение ресурсов
|
||||
zh_syslog_deinit();
|
||||
}
|
||||
```
|
||||
|
||||
### Работа с разными уровнями и facility
|
||||
|
||||
```c
|
||||
#include "zh_syslog.h"
|
||||
|
||||
void log_events(void)
|
||||
{
|
||||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||||
strcpy(config.syslog_ip, "10.0.0.5");
|
||||
zh_syslog_init(&config);
|
||||
|
||||
// Разные facility и severity для разных событий
|
||||
zh_syslog_send(ZH_KERN, ZH_ERR, "dev1", "fw", "kernel error");
|
||||
zh_syslog_send(ZH_LOCAL0, ZH_WARNING, "dev1", "fw", "sensor timeout");
|
||||
zh_syslog_send(ZH_DAEMON, ZH_DEBUG, "dev1", "fw", "loop tick");
|
||||
|
||||
zh_syslog_deinit();
|
||||
}
|
||||
```
|
||||
|
||||
### Отправка длинного сообщения
|
||||
|
||||
```c
|
||||
#include "zh_syslog.h"
|
||||
|
||||
void send_long_message(void)
|
||||
{
|
||||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||||
strcpy(config.syslog_ip, "10.0.0.5");
|
||||
zh_syslog_init(&config);
|
||||
|
||||
// Сообщение длиннее стекового буфера уходит через кучу
|
||||
char big[512];
|
||||
memset(big, 'A', sizeof(big) - 1);
|
||||
big[sizeof(big) - 1] = '\0';
|
||||
zh_syslog_send(ZH_USER, ZH_INFO, "dev1", "app", big);
|
||||
|
||||
zh_syslog_deinit();
|
||||
}
|
||||
```
|
||||
|
||||
## Логирование
|
||||
|
||||
Компонент использует ESP-IDF логирование с тегом `"zh_syslog"`.
|
||||
|
||||
```c
|
||||
esp_log_level_set("zh_syslog", ESP_LOG_ERROR);
|
||||
```
|
||||
|
||||
Ошибки логируются с указанием файла, строки и имени кода ошибки (`esp_err_to_name`).
|
||||
|
||||
## Ошибки
|
||||
|
||||
| Код | Описание |
|
||||
|-----|----------|
|
||||
| `ESP_OK` | Успех |
|
||||
| `ESP_ERR_INVALID_ARG` | Неверный аргумент: `NULL`-указатель, порт вне диапазона, некорректный IP или код вне диапазона |
|
||||
| `ESP_ERR_INVALID_STATE` | Клиент уже инициализирован (`init`) либо ещё не инициализирован (`deinit`/`send`) |
|
||||
| `ESP_ERR_NO_MEM` | Не удалось выделить память под длинное сообщение |
|
||||
| `ESP_FAIL` | Ошибка создания сокета, форматирования или отправки UDP |
|
||||
|
||||
## Ограничения
|
||||
|
||||
1. **`zh_syslog_send()` не потокобезопасна** — проверка флага и работа с сокетом не атомарны; при конкурентном вызове из нескольких задач нужна внешняя синхронизация.
|
||||
2. **Только IPv4** — адрес сервера задаётся строкой и разбирается через `inet_pton(AF_INET, ...)`, IPv6 не поддерживается.
|
||||
3. **Без гарантии доставки** — UDP не подтверждает доставку, потерю сообщений компонент не отслеживает.
|
||||
4. **Длина IP ограничена 15 символами** — поле `syslog_ip[16]` вмещает только IPv4-строку.
|
||||
5. **Требуется активная сеть** — вызывать `zh_syslog_init()` можно только после установления сетевого соединения.
|
||||
6. **Стек 256 байт на сообщение** — сообщения длиннее буфера приводят к аллокации в куче на каждую отправку.
|
||||
|
||||
## Требования для сборки
|
||||
|
||||
- ESP-IDF версии 5.0 и выше.
|
||||
- FreeRTOS (входит в состав ESP-IDF).
|
||||
- lwIP (стек сокетов, входит в состав ESP-IDF).
|
||||
|
||||
## Установка
|
||||
|
||||
```bash
|
||||
cd ваш_проект/components
|
||||
git clone https://github.com/aZholtikov/zh_syslog
|
||||
```
|
||||
|
||||
```c
|
||||
#include "zh_syslog.h"
|
||||
```
|
||||
Reference in new issue
Block a user