| 1 | # zig-tracer |
| 2 | |
| 3 |  |
| 4 | [](https://github.com/nektro/zig-tracer/blob/master/LICENSE) |
| 5 | [](https://github.com/sponsors/nektro) |
| 6 | [](https://ziglang.org/) |
| 7 | [](https://github.com/nektro/zigmod) |
| 8 | |
| 9 | Generic tracing library for Zig, supports multiple backends. |
| 10 | |
| 11 | ## Usage |
| 12 | |
| 13 | in your program: |
| 14 | |
| 15 | ```zig |
| 16 | const std = @import("std"); |
| 17 | const tracer = @import("tracer"); |
| 18 | const nfs = @import("nfs"); |
| 19 | pub const build_options = @import("build_options"); |
| 20 | |
| 21 | pub const tracer_impl = tracer.spall; // see 'Backends' section below |
| 22 | |
| 23 | pub fn main() !void { |
| 24 | try tracer.init(.{}); |
| 25 | defer tracer.deinit(); |
| 26 | |
| 27 | // main loop |
| 28 | while (true) { |
| 29 | try tracer.init_thread(.{nfs.cwd()}); |
| 30 | defer tracer.deinit_thread(); |
| 31 | |
| 32 | handler(); |
| 33 | } |
| 34 | } |
| 35 | |
| 36 | fn handler() void { |
| 37 | const t = tracer.trace(@src()); |
| 38 | defer t.end(); |
| 39 | } |
| 40 | ``` |
| 41 | |
| 42 | ## Backends |
| 43 | |
| 44 | - `none` this is the default and causes tracing calls to become a no-op so that `tracer` can be added to libraries transparently |
| 45 | - `log` uses `std.log` to print on function entrance. |
| 46 | - `chrome` writes a json file in the `chrome://tracing` format described [here](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview) and [here](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool/). |
| 47 | - `spall` writes a binary file compatible with the [Spall](https://gravitymoth.com/spall/) profiler. |
| 48 | - more? feel free to open an issue with requests! |
| 49 | |
| 50 | Any custom backend may also be used that defines the following functions: |
| 51 | |
| 52 | - `pub fn init() !void` |
| 53 | - `pub fn deinit() void` |
| 54 | - `pub fn init_thread(dir: std.fs.Dir) !void` |
| 55 | - `pub fn deinit_thread() void` |
| 56 | - `pub inline fn trace_begin(ctx: tracer.Ctx, comptime ifmt: []const u8, iargs: anytype) void` |
| 57 | - `pub inline fn trace_end(ctx: tracer.Ctx) void` |