aZholtikov/zh_syslog

0 Fork 0

Files

T

aZholtikov da076a19e6 doc: updated wiki

2026-08-16 08:43:56 +03:00

13 KiB

Raw Blame History

zh_syslog — Syslog UDP Client Component for ESP-IDF

Overview
Features
Installation
API Reference
Usage Examples
Technical Specifications
Error Codes
Contributing
License

Overview

zh_syslog is a lightweight syslog UDP client library for ESP-IDF (Espressif IoT Development Framework). It provides an implementation of RFC 5424-compatible syslog message formatting and transmission over UDP datagrams. The library is designed specifically for ESP32/ESP-IDF platforms and integrates seamlessly with FreeRTOS-based applications.

The library enables ESP32 devices to send structured log messages to a remote syslog server, facilitating centralized log management and monitoring in IoT deployments. Messages are formatted according to the RFC 5424 standard, supporting facility codes (0-23) and severity levels (0-7) for precise log categorization.

Features

RFC 5424 Compliance: Messages are formatted according to the RFC 5424 syslog standard
Standard Facility Codes: Support for all 24 standard syslog facility codes (KERN, USER, DAEMON, LOCAL0-LOCAL7, etc.)
Severity Levels: Support for all 8 standard syslog severity levels (EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG)
UDP Transport: Uses datagram sockets for efficient log transmission
DMA-Compatible Memory: Utilizes MALLOC_CAP_8BIT allocations for potential DMA usage
Structured Logging: Includes hostname, app name, and message fields per RFC 5424

Installation

Navigate to your project's components directory:

cd ../your_project/components

Clone the repository:

git clone https://github.com/aZholtikov/zh_syslog

In your application, include the header:

#include "zh_syslog.h"

The component will be automatically built with your project.

API Reference

zh_syslog_init_config_t Structure

Configuration structure for syslog client initialization.

Fields (internal):

Field	Type	Description
`syslog_ip`	`char[16]`	Syslog server IPv4 address as a null-terminated string (e.g., "192.168.1.1"). Maximum 15 characters plus null terminator.
`syslog_port`	`uint32_t`	Syslog server UDP port number (typically 514).

Note: IP address must be a valid IPv4 string. Port should be within valid range (standard syslog port is 514).

zh_syslog_facility_code_t Enum

Standard syslog facility codes per RFC 5424 (0-23).

Values:

Value	Enum	Description
0	`ZH_KERN`	Kernel messages
1	`ZH_USER`	User-level messages
2	`ZH_MAIL`	Mail system
3	`ZH_DAEMON`	System daemons
4	`ZH_AUTH`	Security/authorization messages
5	`ZH_SYSLOG`	Messages from syslogd internally
6	`ZH_LPR`	Line printer subsystem
7	`ZH_NEWS`	Network news subsystem
8	`ZH_UUCP`	UUCP subsystem
9	`ZH_CRON`	Cron subsystem
10	`ZH_AUTHPRIV`	Security/authorization messages (private)
11	`ZH_FTP`	FTP daemon
12	`ZH_NTP`	NTP subsystem
13	`ZH_SECURITY`	Log audit
14	`ZH_CONSOLE`	Log alert
15	`ZH_SOLARIS_CRON`	Scheduling daemon
16-23	`ZH_LOCAL0`-`ZH_LOCAL7`	Local/custom use facilities

zh_syslog_severity_code_t Enum

Standard syslog severity codes per RFC 5424 (0-7).

Values:

Value	Enum	Description
0	`ZH_EMERG`	System is unusable
1	`ZH_ALERT`	Action must be taken immediately
2	`ZH_CRIT`	Critical conditions
3	`ZH_ERR`	Error conditions
4	`ZH_WARNING`	Warning conditions
5	`ZH_NOTICE`	Normal but significant condition
6	`ZH_INFO`	Informational messages
7	`ZH_DEBUG`	Debug-level messages

zh_syslog_init()

Initializes the syslog client by creating a UDP socket and configuring the destination server address.

Parameters:

config - Pointer to zh_syslog_init_config_t with syslog server address and port. Can point to a temporary variable.

Returns:

ESP_OK - Success
ESP_ERR_INVALID_ARG - Config pointer is NULL
ESP_FAIL - Socket creation failed

Example:

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) {
    // Handle initialization error
}

Note: Network connection must be established before calling this function. The config pointer can be temporary. Must not be NULL

zh_syslog_deinit()

Deinitializes the syslog client and releases resources.

Returns:

ESP_OK - Success
ESP_ERR_INVALID_STATE - Client was not initialized

Note: After calling this function, zh_syslog_init() must be called again before any subsequent zh_syslog_send() calls.

zh_syslog_send()

Sends a formatted syslog message to the configured server.

Parameters:

facility - Syslog facility code (0-23) from zh_syslog_facility_code_t
severity - Syslog severity code (0-7) from zh_syslog_severity_code_t
hostname - Pointer to device hostname (alphanumeric characters only, no spaces). Must not be NULL
app_name - Pointer to application name (alphanumeric characters only, no spaces). Must not be NULL
message - Pointer to the message payload string. Must not be NULL

Returns:

ESP_OK - Success
ESP_ERR_INVALID_ARG - hostname, app_name, or message is NULL
ESP_ERR_INVALID_STATE - Client was not initialized
ESP_ERR_NO_MEM - Memory allocation failed (1024 bytes payload buffer)
ESP_FAIL - UDP send operation failed

Example:

zh_syslog_send(ZH_USER, ZH_INFO, "esp32_device", "my_app", "System started");

Note: This function is not thread-safe. Caller must ensure mutual exclusion if multiple tasks may call this function concurrently. Message format follows RFC 5424: <priority>1 timestamp hostname app-name procid msgid - message.

Usage Examples

Basic Example: Initialize and Send Messages

#include "zh_syslog.h"

void app_main(void)
{
    esp_log_level_set("zh_syslog", ESP_LOG_ERROR);
    // Initialize configuration with defaults
    zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
    strcpy(config.syslog_ip, "192.168.1.100");  // Set syslog server IP
    // Initialize syslog client
    esp_err_t ret = zh_syslog_init(&config);
    if (ret != ESP_OK)
    {
        printf("Syslog initialization failed: %s\n", esp_err_to_name(ret));
        return;
    }
    // Send informational message
    zh_syslog_send(ZH_USER, ZH_INFO, "my_device", "my_app", "Application started");
    // Send warning message
    zh_syslog_send(ZH_USER, ZH_WARNING, "my_device", "my_app", "Low battery");
    // Send error message
    zh_syslog_send(ZH_KERN, ZH_ERR, "my_device", "kernel", "Disk read error");
    // Deinitialize when done
    zh_syslog_deinit();
}

Example: Wi-Fi Integration with Periodic Logging

#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 "your_ssid"
#define WIFI_PASS "your_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);
    // Initialize syslog after Wi-Fi connection
    zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
    strcpy(config.syslog_ip, "192.168.1.100");
    zh_syslog_init(&config);
    // Send periodic log messages
    for (int i = 0; i < 10; i++) {
        char msg[64];
        snprintf(msg, sizeof(msg), "Heartbeat #%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);
    }
}

Example: Using Facility and Severity Codes

#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);
    // Kernel critical error
    zh_syslog_send(ZH_KERN, ZH_CRIT, "esp32", "kernel", "Out of memory");
    // User application warning
    zh_syslog_send(ZH_USER, ZH_WARNING, "esp32", "app", "Sensor reading timeout");
    // Auth subsystem notice
    zh_syslog_send(ZH_AUTH, ZH_NOTICE, "esp32", "auth", "User login successful");
    // Local facility for custom logging
    zh_syslog_send(ZH_LOCAL0, ZH_DEBUG, "esp32", "debugger", "Variable state: 0x1234");
    zh_syslog_deinit();
}

Technical Specifications

Parameter	Value
Message Size	1024 bytes (fixed buffer)
Transport Protocol	UDP (SOCK_DGRAM)
Default Port	514
Format Standard	RFC 5424
Memory Allocation	heap_caps_calloc (MALLOC_CAP_8BIT)
Thread Safety	Not thread-safe (caller responsibility)
ESP-IDF Version	>= 5.0
Platform	ESP32 series
Language	C (C99)

Error Codes

Error Code	Description
`ESP_OK`	Operation successful
`ESP_ERR_INVALID_ARG`	Invalid argument (NULL config pointer, NULL hostname/app_name/message)
`ESP_ERR_INVALID_STATE`	Client not initialized (zh_syslog_init not called)
`ESP_ERR_NO_MEM`	Memory allocation failed (out of memory for 1024-byte buffer)
`ESP_FAIL`	Socket creation failed or UDP send operation failed

Contributing

Contributions are welcome! To contribute:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please ensure your code follows the existing style and includes appropriate documentation.

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Additional Notes

UDP Reliability: This library uses UDP which does not guarantee message delivery. For reliable delivery, implement application-level acknowledgment
Performance: O(n) for message formatting (n = message length). Send operation is blocking
Best Practices:
- Always check return values from zh_syslog_init() and zh_syslog_send()
- Call zh_syslog_deinit() before application exit or module unload
- Use facility codes to categorize log sources (KERN for OS, USER for app, LOCAL0-7 for custom)
- Keep hostname and app_name alphanumeric (no spaces) per RFC 5424
- Set appropriate log level filtering on the syslog server to avoid excessive traffic

Generated for zh_syslog v1.0.0

13 KiB Raw Blame History

zh_syslog — Syslog UDP Client Component for ESP-IDF

Table of Contents

Overview

Features

Installation

API Reference

zh_syslog_init_config_t Structure

zh_syslog_facility_code_t Enum

zh_syslog_severity_code_t Enum

zh_syslog_init()

zh_syslog_deinit()

zh_syslog_send()

Usage Examples

Basic Example: Initialize and Send Messages

Example: Wi-Fi Integration with Periodic Logging

Example: Using Facility and Severity Codes

Technical Specifications

Error Codes

Contributing

License

Apache License, Version 2.0

Additional Notes

13 KiB

Raw Blame History