# journalz A Zig library for writing structured log messages directly to the systemd journal over its native datagram socket at `/run/systemd/journal/socket`. Talking to the socket directly means a message carries its own fields rather than being flattened into a line of text. Every message is built up in a `memfd`, sealed against further writes, and handed to the journal as an `SCM_RIGHTS` file descriptor over `sendmsg`, so there is no size limit to work around and the journal reads the payload the sender can no longer change. Sending is done through a `std.Io`, which the caller supplies, so the library names no I/O implementation of its own. The API documentation is generated from the doc comments, which carry most of the explanation, and is published at . `zig build docs-serve` reads the same thing locally -- it has to be served rather than opened, since the viewer fetches its sources at runtime. ```zig const journalz = @import("journalz"); const logger: journalz.Logger = try .init(io, "myprogram", .DAEMON); defer logger.deinit(); // A formatted MESSAGE field, with failures swallowed. logger.info("listening on port {d}", .{port}); // Or build the fields yourself. const msg = try logger.message(.INFO); errdefer msg.cancel(); var buf: [1024]u8 = undefined; var w = msg.writer(&buf); try w.writeAll("MESSAGE", "connection accepted"); try w.print("REMOTE_ADDR", "{f}", .{addr}); try w.writeSrc(@src()); try w.flush(); try msg.send(); ``` ## Routing `std.log` to the journal `examples/std_log.zig` replaces `std.Options.logFn`, so that everything the program and its libraries already log through `std.log` lands in the journal. The level becomes a real syslog priority and the scope becomes a field, which means journald indexes both: ```console journalctl --identifier=journalz-example --priority=warning journalctl --identifier=journalz-example LOG_SCOPE=database ``` rather than leaving a reader to grep for `warning:` and `(database)` in a line of text. The example is built by `zig build` and run against a real journald by the NixOS check, so it cannot quietly stop working. ## Where this lives The canonical repository is on Forgejo, with mirrors on Tangled and Radicle: ```console git clone https://git.jcollie.dev/jeff/journalz.git ``` - Forgejo — - Tangled — ### Radicle The repository is also on [Radicle](https://radicle.xyz/), where its Repository ID is the only way to find it: ``` rad:z4LAwD5xmrZ9WB8HmbV65Q2PEmsDX ``` ```console rad clone rad:z4LAwD5xmrZ9WB8HmbV65Q2PEmsDX ``` ## Building The build needs nothing beyond Zig 0.17.0; the flake's devshell provides it. ```console nix develop -c zig build test nix develop -c zig build check ``` For Zig 0.16.0, use the `zig-0.16` branch, which holds the last of journalz to build with it: ```console git clone -b zig-0.16 https://git.jcollie.dev/jeff/journalz.git ``` or, as a dependency: ```console zig fetch --save https://git.jcollie.dev/jeff/journalz/archive/zig-0.16.tar.gz ``` The `v0.1.0` tag also predates the move to 0.17 and builds with 0.16.0. ## Testing The unit tests talk to a fake journald of their own -- a Unix datagram socket that receives the message, pulls the sealed memfd out of the ancillary data and decodes the wire format back into fields. So they assert on what actually crossed the socket, and they run anywhere, including in a Nix build sandbox with no systemd present. What they cannot show is that systemd-journald agrees, since the decoder they check against was written from the same understanding as the encoder. That is what the NixOS virtual machine check is for: it boots a machine with a real journald, runs `tests/e2e.zig` against it, and reads the entries back out of `journalctl` -- the priorities, the caller's own indexed fields, a value with newlines in it, and a 256 KiB field that no datagram could have carried. ```console nix flake check # everything, virtual machine included nix build .#checks.x86_64-linux.journald # just the journald machine ``` ## License MIT. See [LICENSE](LICENSE).