Debugging

zero-native provides structured tracing, persistent logging, panic capture, and diagnostic tools for debugging desktop apps.

Trace modes

The runtime emits structured trace records. Control verbosity with TraceMode:

Enable at build time with -Dtrace=true, or parse from a string:

const mode = zero_native.debug.parseTraceMode("all"); // returns ?TraceMode

Trace sinks

Trace records are routed through sinks. zero-native provides three:

FileTraceSink -- appends records to a file on disk:

var file_sink = zero_native.debug.FileTraceSink.init(io, log_dir, log_file, .json_lines);

FanoutTraceSink -- broadcasts to multiple child sinks (e.g. stdout + file):

var sinks = [_]trace.Sink{ stdout_sink.sink(), file_sink.sink() };
var fanout = zero_native.debug.FanoutTraceSink{ .sinks = &sinks };

StdoutTraceSink (from zero-native's trace module) -- writes to stdout for interactive development.

Wire a sink into the runtime via RuntimeOptions.trace_sink:

var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .trace_sink = fanout.sink(),
});

Log format

The ZERO_NATIVE_LOG_FORMAT environment variable controls the persistent log format:

Log paths

Default log file locations by platform:

Override with ZERO_NATIVE_LOG_DIR:

ZERO_NATIVE_LOG_DIR=/tmp/my-logs zig build run-webview

Panic capture

zero-native captures Zig panics before the default handler runs:

1. Writes a report to last-panic.txt in the log directory (includes panic message and return address)
2. Appends a fatal trace record to the log file
3. Invokes std.debug.defaultPanic for the normal Zig panic output

Enable in your app:

pub const panic = std.debug.FullPanic(zero_native.debug.capturePanic);

Then call installPanicCapture during startup:

zero_native.debug.installPanicCapture(io, log_setup.paths);

Debug overlay

Build with -Ddebug-overlay=true to enable a visual debugging overlay in the WebView. This shows frame timing, invalidation regions, and window metadata.

zig build run-webview -Ddebug-overlay=true

See also zero-native doctor for a full diagnostic tool reference.

Environment variables