Zig syslog client

This is a syslog client library for Zig:

Protocols	UDP, TCP
RFC	Subset of RFC5424
Tested on	Mac, Windows, Linux

For the curious: IT Explained: Syslog

Hello, Zig!

When client code calls

    logger.write_info("Hello, Zig!");

syslog client sends following text message to syslog receiver process:

<190>1 2024-10-09T09:07:11+00:00 BLKF zigprocess 18548 1 - Hello, Zig!

Let's see what this message consist of:

Value	RFC Definition	Description
190	PRIVAL	Priority
1	VERSION	Always 1
2024-10-09T09:07:11+00:00	TIMESTAMP	FULL-DATE "T" FULL-TIME
BLKF	HOSTNAME	Hostname or '-'
zigprocess	APP-NAME	Application name provided by caller
18548	PROCID	Process ID or '-'
1	MSGID	Message ID - sequential number generated automatically
-	STRUCTURED-DATA	Always '-'
Hello, Zig!	MSG	Message

Priority

         Priority = Facility * 8 + Severity 

Facility represents the machine process that created the Syslog event

rfc5424.Facility	Value	Description
.kern	0	kernel messages
.user	1	random user-level messages
.mail	2	mail system
.daemon	3	system daemons
.auth	4	security/authorization messages
.syslog	5	messages generated internally by syslogd
.lpr	6	line printer subsystem
.news	7	network news subsystem
.uucp	8	UUCP subsystem
.cron	9	clock daemon
.authpriv	10	security/authorization messages (private)
.ftp	11	ftp daemon
.local0	16	local use 0
.local1	17	local use 1
.local2	18	local use 2
.local3	19	local use 3
.local4	20	local use 4
.local5	21	local use 5
.local6	22	local use 6
.local7	23	local use 7

Severity describes the severity level of the syslog message in question.

Level	rfc5424.Severity	Description
0	.emerg	system is unusable
1	.alert	action must be taken immediately
2	.crit	critical conditions
3	.err	error conditions
4	.warning	warning conditions
5	.notice	normal but significant condition
6	.info	informational
7	.debug	debug-level messages

Quiz

What are Facility and Severity of "Hello, Zig!" message?

For leisure time

• What is Syslog?
• syslog-ng Open Source Edition
• The rocket-fast system for log processing
• Old brave syslogd
• Kafka syslog connector
• Nats syslog connector

Installation

Add syslog to build.zig.zon:

zig fetch --save=syslog git+https://github.com/g41797/syslog

Add syslog to build.zig:

    const syslog = b.dependency("syslog", .{
        .target = target,
        .optimize = optimize,
    });

    const lib = b.addStaticLibrary(..);
    lib.root_module.addImport("syslog", syslog.module("syslog"));

    const lib_unit_tests = b.addTest(...);
    lib_unit_tests.root_module.addImport("syslog", syslog.module("syslog"));

Import syslog:

const syslog = @import("syslog");

Usage

Configuration

syslog uses following configuration:

pub const SyslogOpts = struct {
    // application:
    name: []const u8 = "zigprocess",
    fcl: rfc5424.Facility = .local7,

    // transport:
    proto: Protocol = .udp,
    addr: []const u8 = "127.0.0.1",
    port: u16 = 514,
};

Initialization

    var logger: syslog.Syslog = .{};
    try logger.init(std.testing.allocator, .{
        .name = "runner",
        .fcl = .daemon
        .port = 12345,
    });
    defer logger.deinit();

After initialization you can call syslog on different threads.

Logging

There are two groups of APIs:

• write: message is straight text

    pub inline fn write_<severity>(slog: *Syslog, msg: []const u8) !void {...}
    ....
    logger.write_debug("Hello, Zig!");

• print: message will be formatted before send

    pub inline fn print_<severity>(slog: *Syslog, comptime fmt: []const u8, msg: anytype) !void {...}
    ....
    const name = "World";
    logger.print_debug("Hello, {s}!", .{name});

Filtering

Set filter:

    // disable send messages with .info & .debug severities
    logger.setfilter(.info);// disable send messages with .info & .debug severities 

Reset filter:

    logger.setfilter(null); 

License

MIT

Powered by