Yves Biener
dda2199706
All checks were successful
Zig Project Action / Lint, Spell-check and test zig project (push) Successful in 53s
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# zlog
|
|
|
|
Standard Library log wrapper. `zlog` provides adjusted `std.log` output and a pretty print function for easy overwriting of user defined types (`struct`, `enum`, `union` and `vector`).
|
|
|
|
## Usage
|
|
|
|
The following snippet shows an example usage of `zlog` to change the default log format and add pretty printing to both user defined types (`Options` and `Struct`):
|
|
|
|
```zig
|
|
const std = @import("std");
|
|
const zlog = @import("zlog");
|
|
|
|
// use this to overwrite the default log format of `std.log`
|
|
pub const std_options = zlog.std_options;
|
|
|
|
const Options = enum {
|
|
a,
|
|
b,
|
|
c,
|
|
|
|
// copy and paste this function into your user defined types to enable pretty printing for these types
|
|
pub fn format(value: @This(), comptime fmt: []const u8, options: std.fmt.FormatOptions, writer: anytype) anyerror!void {
|
|
try zlog.pretty_format(value, fmt, options, writer);
|
|
}
|
|
};
|
|
|
|
const Struct = struct {
|
|
a: usize = 42,
|
|
b: bool = true,
|
|
c: [5]u16 = .{ 1, 2, 3, 4, 5 },
|
|
d: []const u8 = "string",
|
|
e: Options = Options.b,
|
|
|
|
// same function as above...
|
|
pub fn format(value: @This(), comptime fmt: []const u8, options: std.fmt.FormatOptions, writer: anytype) anyerror!void {
|
|
try zlog.pretty_format(value, fmt, options, writer);
|
|
}
|
|
};
|
|
|
|
pub fn main() void {
|
|
// initialize zlog with the scope of `main`
|
|
const log = std.log.scoped(.main);
|
|
// NOTE: the scope of `default` will result in no scoping being printed in
|
|
// the resulting output (default behavior of `std.log.defaultLog`)
|
|
|
|
// some variables to log
|
|
const int_var = 42;
|
|
const array_var = [_]i32{ 1, 2, 3, 4 };
|
|
const string_var = "This is a test";
|
|
const option_var = Options.a;
|
|
const struct_var: Struct = .{};
|
|
|
|
// NOTE: Depending on the optimization target some of these log messages
|
|
// will not show, which is inline with the behavior of `std.log`.
|
|
log.debug("Debug message {any}", .{int_var});
|
|
log.info("Info message {any}", .{array_var});
|
|
log.info("Info message \"{s}\"", .{string_var});
|
|
log.warn("Warning message {any}", .{option_var});
|
|
log.err("Error message {any}", .{struct_var});
|
|
}
|
|
```
|
|
|
|
This will result in the following output:
|
|
|
|
```
|
|
[2024-08-28 22:22] debug(main): Debug message 42
|
|
[2024-08-28 22:22] info(main): Info message { 1, 2, 3, 4 }
|
|
[2024-08-28 22:22] info(main): Info message "This is a test"
|
|
[2024-08-28 22:22] warning(main): Warning message main.Options = enum {
|
|
a,
|
|
b,
|
|
c,
|
|
} = a
|
|
[2024-08-28 22:22] error(main): Error message main.Struct = struct {
|
|
.a = 42,
|
|
.b = true,
|
|
.c = []u16: { 1, 2, 3, 4, 5 },
|
|
.d = { 115, 116, 114, 105, 110, 103 },
|
|
.e = main.Options = enum {
|
|
a,
|
|
b,
|
|
c,
|
|
} = b,
|
|
}
|
|
```
|
|
|
|
## Customization
|
|
|
|
For more details about the output customization see the configuration options of the `zlog` module. Following options are available:
|
|
|
|
- _timestamp_ (default: `true`): Prepend the current timestamp before each log message.
|
|
- _stderr_ (default: `true`): Print log messages to stderr. **NOTE**: Currently not working as log output is not appended and only the last log message will be in the resulting log file! This is a not-yet-implemented feature of the standard library of zig! See this [issue](https://github.com/ziglang/zig/issues/14375) for more details.
|
|
|
|
## Tips
|
|
|
|
The following list shows some tips on how to use logging more effectively. These tips do not apply just to `zlog` (and not even only to zig code).
|
|
|
|
- Use `errdefer` to directly print messages on failures in the same function they occur:
|
|
```zig
|
|
// assume log is already defined before (with the corresponding scope)
|
|
const port = port: {
|
|
errdefer |err| log.err("failed to read the port number: {}", .{err});
|
|
|
|
var buf: [fmt.count("{}\n", .{maxInt(u16)})]u8 = undefined;
|
|
const len = try process.stdout.?.readAll(&buf);
|
|
break :port try fmt.parseInt(u16, buf[0 .. len -| 1], 10);
|
|
};
|
|
```
|