Yves Biener
7889a6ec7a
NOTE: file logging will not work correctly yet due to opening files appending using the std is currently not implemented (as of zig version 0.13.0)!
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 0.13.0! 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);
|
|
};
|
|
```
|