Debugging

The Native SDK 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 = native_sdk.debug.parseTraceMode("all"); // returns ?TraceMode

Trace sinks

Trace records are routed through sinks. the Native SDK provides three:

FileTraceSink -- appends records to a file on disk:

var file_sink = native_sdk.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 = native_sdk.debug.FanoutTraceSink{ .sinks = &sinks };

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

Wire a sink into the runtime via RuntimeOptions.trace_sink:

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

Log format

The NATIVE_SDK_LOG_FORMAT environment variable controls the persistent log format:

Log paths

Default log file locations by platform:

Override with NATIVE_SDK_LOG_DIR:

NATIVE_SDK_LOG_DIR=/tmp/my-logs native dev

Panic capture

The Native SDK 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(native_sdk.debug.capturePanic);

Then call installPanicCapture during startup:

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

Debug overlay

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

native dev -Ddebug-overlay=true

See also native doctor for a full diagnostic tool reference.

Environment variables