399 lines
19 KiB
Markdown
399 lines
19 KiB
Markdown
# zh_syslog — Компонент syslog UDP клиента для ESP-IDF
|
||
|
||
## Содержание
|
||
|
||
- [Обзор](#обзор)
|
||
- [Возможности](#возможности)
|
||
- [Установка](#установка)
|
||
- [Справочник API](#справочник-api)
|
||
- [Примеры использования](#примеры-использования)
|
||
- [Технические характеристики](#технические-характеристики)
|
||
- [Коды ошибок](#коды-ошибок)
|
||
- [Вклад в проект](#вклад-в-проект)
|
||
- [Лицензия](#лицензия)
|
||
|
||
---
|
||
|
||
## Обзор
|
||
|
||
`zh_syslog` — это легковесная библиотека syslog UDP клиента для ESP-IDF (Espressif IoT Development Framework). Она предоставляет реализацию формирования и передачи syslog-сообщений совместимых со стандартом RFC 5424 через UDP дейтаграммы. Библиотека разработана специально для платформ ESP32/ESP-IDF и бесшовно интегрируется с приложениями на базе FreeRTOS.
|
||
|
||
Библиотека позволяет устройствам ESP32 отправлять структурированные журнальные сообщения на удалённый syslog-сервер, что способствует централизованному управлению журналами и мониторингу в IoT-развертываниях. Сообщения форматируются в соответствии со стандартом RFC 5424, поддерживая коды facility (0-23) и уровни важности (0-7) для точной категоризации журналов.
|
||
|
||
---
|
||
|
||
## Возможности
|
||
|
||
1. **Соответствие RFC 5424**: Сообщения форматируются в соответствии со стандартом syslog RFC 5424
|
||
2. **Стандартные коды Facility**: Поддержка всех 24 стандартных кодов facility syslog (KERN, USER, DAEMON, LOCAL0-LOCAL7 и т.д.)
|
||
3. **Уровни важности**: Поддержка всех 8 стандартных уровней severity syslog (EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG)
|
||
4. **UDP транспорт**: Использует дейтаграммные сокеты для эффективной передачи журналов
|
||
5. **Память совместимая с DMA**: Использует выделения MALLOC_CAP_8BIT для потенциального использования DMA
|
||
6. **Структурированное логирование**: Включает поля hostname, app name и message в соответствии с RFC 5424
|
||
|
||
---
|
||
|
||
## Установка
|
||
|
||
Перейдите в каталог компонентов вашего проекта:
|
||
|
||
```bash
|
||
cd ../ваш_проект/components
|
||
```
|
||
|
||
Клонируйте репозиторий:
|
||
|
||
```bash
|
||
git clone https://github.com/aZholtikov/zh_syslog
|
||
```
|
||
|
||
В вашем приложении подключите заголовочный файл:
|
||
|
||
```c
|
||
#include "zh_syslog.h"
|
||
```
|
||
|
||
Компонент будет автоматически собран вместе с вашим проектом.
|
||
|
||
---
|
||
|
||
## Справочник API
|
||
|
||
### Структура zh_syslog_init_config_t
|
||
|
||
Структура конфигурации для инициализации syslog клиента.
|
||
|
||
**Поля (внутренние):**
|
||
|
||
| Поле | Тип | Описание |
|
||
| ------ | ------ | ---------- |
|
||
| `syslog_ip` | `char[16]` | IPv4-адрес syslog сервера в виде нуль-терминированной строки (например, "192.168.1.1"). Максимум 15 символов плюс нуль-терминатор. |
|
||
| `syslog_port` | `uint32_t` | UDP-порт syslog сервера (обычно 514). |
|
||
|
||
**Примечание:** IP-адрес должен быть валидной IPv4-строкой. Порт должен быть в допустимом диапазоне (стандартный порт syslog — 514).
|
||
|
||
---
|
||
|
||
### Перечисление zh_syslog_facility_code_t
|
||
|
||
Стандартные коды facility syslog в соответствии с RFC 5424 (0-23).
|
||
|
||
**Значения:**
|
||
|
||
| Значение | Перечисление | Описание |
|
||
| ---------- | -------------- | ---------- |
|
||
| 0 | `ZH_KERN` | Сообщения ядра |
|
||
| 1 | `ZH_USER` | Пользовательские сообщения |
|
||
| 2 | `ZH_MAIL` | Почтовая система |
|
||
| 3 | `ZH_DAEMON` | Системные демоны |
|
||
| 4 | `ZH_AUTH` | Сообщения безопасности/авторизации |
|
||
| 5 | `ZH_SYSLOG` | Сообщения от самого syslogd |
|
||
| 6 | `ZH_LPR` | Подсистема принтеров |
|
||
| 7 | `ZH_NEWS` | Сетевая подсистема новостей |
|
||
| 8 | `ZH_UUCP` | Подсистема UUCP |
|
||
| 9 | `ZH_CRON` | Подсистема cron |
|
||
| 10 | `ZH_AUTHPRIV` | Сообщения безопасности (приватные) |
|
||
| 11 | `ZH_FTP` | FTP демон |
|
||
| 12 | `ZH_NTP` | Подсистема NTP |
|
||
| 13 | `ZH_SECURITY` | Журнал аудита |
|
||
| 14 | `ZH_CONSOLE` | Журнал уведомлений |
|
||
| 15 | `ZH_SOLARIS_CRON` | Планировщик задач |
|
||
| 16-23 | `ZH_LOCAL0`-`ZH_LOCAL7` | Локальное/пользовательское использование |
|
||
|
||
---
|
||
|
||
### Перечисление zh_syslog_severity_code_t
|
||
|
||
Стандартные коды severity syslog в соответствии с RFC 5424 (0-7).
|
||
|
||
**Значения:**
|
||
|
||
| Значение | Перечисление | Описание |
|
||
| ---------- | -------------- | ---------- |
|
||
| 0 | `ZH_EMERG` | Система неработоспособна |
|
||
| 1 | `ZH_ALERT` | Необходимо немедленное действие |
|
||
| 2 | `ZH_CRIT` | Критические условия |
|
||
| 3 | `ZH_ERR` | Ошибки |
|
||
| 4 | `ZH_WARNING` | Предупреждения |
|
||
| 5 | `ZH_NOTICE` | Обычные, но значимые условия |
|
||
| 6 | `ZH_INFO` | Информационные сообщения |
|
||
| 7 | `ZH_DEBUG` | Сообщения отладки |
|
||
|
||
---
|
||
|
||
### zh_syslog_init()
|
||
|
||
Инициализирует syslog клиент путём создания UDP сокета и настройки адреса целевого сервера.
|
||
|
||
**Параметры:**
|
||
|
||
- `config` — Указатель на `zh_syslog_init_config_t` с адресом и портом syslog сервера. Может указывать на временную переменную. Не должен быть NULL
|
||
|
||
**Возвращает:**
|
||
|
||
- `ESP_OK` — Успех
|
||
- `ESP_ERR_INVALID_ARG` — Указатель config равен NULL
|
||
- `ESP_FAIL` — Создание сокета не удалось
|
||
|
||
**Пример:**
|
||
|
||
```c
|
||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||
strcpy(config.syslog_ip, "192.168.1.100");
|
||
esp_err_t ret = zh_syslog_init(&config);
|
||
if (ret != ESP_OK) {
|
||
// Обработка ошибки инициализации
|
||
}
|
||
```
|
||
|
||
**Примечание:** Подключение к сети должно быть установлено перед вызовом этой функции. Указатель config может быть временным.
|
||
|
||
---
|
||
|
||
### zh_syslog_deinit()
|
||
|
||
Деинициализирует syslog клиент и освобождает ресурсы.
|
||
|
||
**Возвращает:**
|
||
|
||
- `ESP_OK` — Успех
|
||
- `ESP_ERR_INVALID_STATE` — Клиент не был инициализирован
|
||
|
||
**Примечание:** После вызова этой функции `zh_syslog_init()` должна быть вызвана заново перед любыми последующими вызовами `zh_syslog_send()`.
|
||
|
||
---
|
||
|
||
### zh_syslog_send()
|
||
|
||
Отправляет отформатированное syslog-сообщение на настроенный сервер.
|
||
|
||
**Параметры:**
|
||
|
||
- `facility` — Код facility syslog (0-23) из `zh_syslog_facility_code_t`
|
||
- `severity` — Код severity syslog (0-7) из `zh_syslog_severity_code_t`
|
||
- `hostname` — Указатель на имя устройства (только алфавитно-цифровые символы, без пробелов). Не должен быть NULL
|
||
- `app_name` — Указатель на имя приложения (только алфавитно-цифровые символы, без пробелов). Не должен быть NULL
|
||
- `message` — Указатель на строку содержимого сообщения. Не должен быть NULL
|
||
|
||
**Возвращает:**
|
||
|
||
- `ESP_OK` — Успех
|
||
- `ESP_ERR_INVALID_ARG` — hostname, app_name или message равен NULL
|
||
- `ESP_ERR_INVALID_STATE` — Клиент не инициализирован
|
||
- `ESP_ERR_NO_MEM` — Ошибка выделения памяти (буфер 1024 байта)
|
||
- `ESP_FAIL` — Операция отправки UDP не удалась
|
||
|
||
**Пример:**
|
||
|
||
```c
|
||
zh_syslog_send(ZH_USER, ZH_INFO, "esp32_device", "my_app", "Приложение запущено");
|
||
```
|
||
|
||
**Примечание:** Эта функция не является потокобезопасной. Вызывающий должен обеспечить взаимное исключение, если несколько задач могут вызывать эту функцию одновременно. Формат сообщения соответствует RFC 5424: `<priority>1 timestamp hostname app-name procid msgid - message`.
|
||
|
||
---
|
||
|
||
## Примеры использования
|
||
|
||
### Базовый пример: Инициализация и отправка сообщений
|
||
|
||
```c
|
||
#include "zh_syslog.h"
|
||
|
||
void app_main(void)
|
||
{
|
||
esp_log_level_set("zh_syslog", ESP_LOG_ERROR);
|
||
// Инициализация конфигурации со значениями по умолчанию
|
||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||
strcpy(config.syslog_ip, "192.168.1.100"); // IP syslog сервера
|
||
// Инициализация syslog клиента
|
||
esp_err_t ret = zh_syslog_init(&config);
|
||
if (ret != ESP_OK)
|
||
{
|
||
printf("Ошибка инициализации syslog: %s\n", esp_err_to_name(ret));
|
||
return;
|
||
}
|
||
// Отправка информационного сообщения
|
||
zh_syslog_send(ZH_USER, ZH_INFO, "my_device", "my_app", "Приложение запущено");
|
||
// Отправка предупреждения
|
||
zh_syslog_send(ZH_USER, ZH_WARNING, "my_device", "my_app", "Низкий заряд батареи");
|
||
// Отправка сообщения об ошибке
|
||
zh_syslog_send(ZH_KERN, ZH_ERR, "my_device", "kernel", "Ошибка чтения диска");
|
||
// Деинициализация при завершении
|
||
zh_syslog_deinit();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Пример: Интеграция с Wi-Fi и периодическая отправка журналов
|
||
|
||
```c
|
||
#include "nvs_flash.h"
|
||
#include "esp_netif.h"
|
||
#include "esp_wifi.h"
|
||
#include "esp_event.h"
|
||
#include "freertos/FreeRTOS.h"
|
||
#include "freertos/event_groups.h"
|
||
#include "zh_syslog.h"
|
||
|
||
#define WIFI_SSID "ваш_ssid"
|
||
#define WIFI_PASS "ваш_password"
|
||
#define WIFI_CONNECT_SUCCESS BIT0
|
||
|
||
static EventGroupHandle_t s_event_group;
|
||
static const int WIFI_CONNECTED_BIT = BIT0;
|
||
|
||
static void wifi_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data);
|
||
|
||
void app_main(void)
|
||
{
|
||
esp_log_level_set("zh_syslog", ESP_LOG_ERROR);
|
||
nvs_flash_init();
|
||
esp_netif_init();
|
||
esp_event_loop_create_default();
|
||
esp_netif_create_default_wifi_sta();
|
||
wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
|
||
esp_wifi_init(&cfg);
|
||
wifi_config_t wifi_config = {
|
||
.sta = {
|
||
.ssid = WIFI_SSID,
|
||
.password = WIFI_PASS,
|
||
},
|
||
};
|
||
esp_wifi_set_mode(WIFI_MODE_STA);
|
||
esp_wifi_set_config(WIFI_IF_STA, &wifi_config);
|
||
esp_event_handler_instance_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL, NULL);
|
||
esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &wifi_event_handler, NULL, NULL);
|
||
esp_wifi_start();
|
||
s_event_group = xEventGroupCreate();
|
||
xEventGroupWaitBits(s_event_group, WIFI_CONNECTED_BIT, pdFALSE, pdTRUE, portMAX_DELAY);
|
||
// Инициализация syslog после подключения Wi-Fi
|
||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||
strcpy(config.syslog_ip, "192.168.1.100");
|
||
zh_syslog_init(&config);
|
||
// Периодическая отправка журнальных сообщений
|
||
for (int i = 0; i < 10; i++) {
|
||
char msg[64];
|
||
snprintf(msg, sizeof(msg), "Сердцебитие #%d", i + 1);
|
||
zh_syslog_send(ZH_USER, ZH_INFO, "esp32_sensor", "logger", msg);
|
||
vTaskDelay(1000 / portTICK_PERIOD_MS);
|
||
}
|
||
zh_syslog_deinit();
|
||
}
|
||
|
||
static void wifi_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
|
||
{
|
||
if (event_id == IP_EVENT_STA_GOT_IP)
|
||
{
|
||
xEventGroupSetBits(s_event_group, WIFI_CONNECTED_BIT);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Пример: Использование кодов Facility и Severity
|
||
|
||
```c
|
||
#include "zh_syslog.h"
|
||
|
||
void app_main(void)
|
||
{
|
||
esp_log_level_set("zh_syslog", ESP_LOG_ERROR);
|
||
zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
|
||
strcpy(config.syslog_ip, "192.168.1.100");
|
||
zh_syslog_init(&config);
|
||
// Критическая ошибка ядра
|
||
zh_syslog_send(ZH_KERN, ZH_CRIT, "esp32", "kernel", "Недостаточно памяти");
|
||
// Предупреждение пользовательского приложения
|
||
zh_syslog_send(ZH_USER, ZH_WARNING, "esp32", "app", "Таймаут чтения сенсора");
|
||
// Уведомление подсистемы аутентификации
|
||
zh_syslog_send(ZH_AUTH, ZH_NOTICE, "esp32", "auth", "Пользователь успешно вошёл");
|
||
// Локальный facility для пользовательского логирования
|
||
zh_syslog_send(ZH_LOCAL0, ZH_DEBUG, "esp32", "debugger", "Состояние переменной: 0x1234");
|
||
zh_syslog_deinit();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Технические характеристики
|
||
|
||
| Параметр | Значение |
|
||
| ---------- | ---------- |
|
||
| **Размер сообщения** | 1024 байта (фиксированный буфер) |
|
||
| **Транспортный протокол** | UDP (SOCK_DGRAM) |
|
||
| **Порт по умолчанию** | 514 |
|
||
| **Стандарт форматирования** | RFC 5424 |
|
||
| **Выделение памяти** | heap_caps_calloc (MALLOC_CAP_8BIT) |
|
||
| **Потокобезопасность** | Не потокобезопасна (ответственность вызывающего) |
|
||
| **Версия ESP-IDF** | >= 5.0 |
|
||
| **Платформа** | Серия ESP32 |
|
||
| **Язык** | C (C99) |
|
||
|
||
---
|
||
|
||
## Коды ошибок
|
||
|
||
| Код ошибки | Описание |
|
||
| ------------ | ---------- |
|
||
| `ESP_OK` | Операция выполнена успешно |
|
||
| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL config, NULL hostname/app_name/message) |
|
||
| `ESP_ERR_INVALID_STATE` | Клиент не инициализирован (zh_syslog_init не вызвана) |
|
||
| `ESP_ERR_NO_MEM` | Ошибка выделения памяти (не хватает памяти для буфера 1024 байта) |
|
||
| `ESP_FAIL` | Создание сокета не удалось или операция отправки UDP не удалась |
|
||
|
||
---
|
||
|
||
## Вклад в проект
|
||
|
||
Вклад приветствуется! Чтобы внести свой вклад:
|
||
|
||
1. Сделайте форк репозитория
|
||
2. Создайте ветку функции (`git checkout -b feature/AmazingFeature`)
|
||
3. Закоммитьте ваши изменения (`git commit -m 'Add some AmazingFeature'`)
|
||
4. Отправьте в ветку (`git push origin feature/AmazingFeature`)
|
||
5. Откройте Pull Request
|
||
|
||
Пожалуйста, убедитесь, что ваш код следует существующему стилю и включает соответствующую документацию.
|
||
|
||
---
|
||
|
||
## Лицензия
|
||
|
||
Этот проект лицензирован по лицензии Apache, версия 2.0 - см. файл [LICENSE](LICENSE) для подробной информации.
|
||
|
||
### Apache License, Version 2.0
|
||
|
||
Авторское право (c) 2026 Алексей Жолтиков
|
||
|
||
Лицензировано по лицензии Apache License, Version 2.0 (далее — "Лицензия");
|
||
вы не можете использовать этот файл, кроме случаев, предусмотренных Лицензией.
|
||
Копию Лицензии можно получить по адресу:
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
Если иное не требуется действующим законодательством или не согласовано в письменном виде,
|
||
программное обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ",
|
||
БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, явных или подразумеваемых, включая, но не ограничиваясь, гарантии
|
||
ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
|
||
Смотрите Лицензию для получения конкретных прав и ограничений.
|
||
|
||
---
|
||
|
||
## Дополнительные заметки
|
||
|
||
- **Надёжность UDP**: Эта библиотека использует UDP, который не гарантирует доставку сообщений. Для надёжной доставки реализуйте приложение-уровень подтверждения
|
||
- **Производительность**: O(n) для форматирования сообщения (n = длина сообщения). Операция отправки блокирующая
|
||
- **Лучшие практики**:
|
||
- Всегда проверяйте возвращаемые значения от zh_syslog_init() и zh_syslog_send()
|
||
- Вызывайте zh_syslog_deinit() перед выходом из приложения или выгрузкой модуля
|
||
- Используйте коды facility для категоризации источников журналов (KERN для ОС, USER для приложения, LOCAL0-7 для пользовательских)
|
||
- Держите hostname и app_name алфавитно-цифровыми (без пробелов) в соответствии с RFC 5424
|
||
- Настройте соответствующий уровень фильтрации журналов на syslog-сервере, чтобы избежать избыточного трафика
|
||
|
||
---
|
||
|
||
*Сгенерировано для zh_syslog v1.0.0*
|