Module trace_recorder 

Trace recording and data model.

All tracing instrumentation in Zng projects is done using the tracing crate, trace recording is done using the tracing-chrome crate. The recorded traces can be viewed in chrome://tracing or ui.perfetto.dev and can be parsed by the Trace data model.

Build the app with "trace_recorder" and run the with the "ZNG_RECORD_TRACE" env var set to record all other processes spawned by the app.

use zng::prelude::*;

fn main() {
    unsafe {
        std::env::set_var("ZNG_RECORD_TRACE", "");
    }
    unsafe {
        std::env::set_var("ZNG_RECORD_TRACE_FILTER", "debug");
    }

    // recording start here for all app processes when ZNG_RECORD_TRACE is set.
    zng::env::init!();

    // .. app
}

The example above hardcodes trace recording for all app processes by setting the "ZNG_RECORD_TRACE" environment variable before the init!() call. It also sets "ZNG_RECORD_TRACE_FILTER" to a slightly less verbose level.

Config

The "ZNG_RECORD_TRACE_DIR" variable can be set to define a custom output directory path, relative to the current dir. The default dir is "./zng-trace/".

The "ZNG_RECORD_TRACE_FILTER" or "RUST_LOG" variables can be used to set custom tracing filters, see the filter syntax for details. The default filter is "trace" that records all spans and events.

Output

Raw trace files are saved to "{ZNG_RECORD_TRACE_DIR}/{timestamp}/{pid}.json".

The timestamp is in microseconds from Unix epoch and is defined by the first process that runs. All processes are recorded to the same timestamp folder.

The process name is defined by an event INFO message that reads "pid: {pid}, name: {name}". See zng::env::process_name for more details.

The process record start timestamp is defined by an event INFO message that reads "zng-record-start: {timestamp}". This timestamp is also in microseconds from Unix epoch.

Cargo Zng

You can also use the cargo zng trace subcommand to record traces, it handles setting the env variables, merges the multi process traces into a single file and properly names the processes for better compatibility with trace viewers.

cargo zng trace --filter debug "path/my-exe"

You can also run using custom commands after --:

cargo zng trace -- cargo run my-exe

Call cargo zng trace --help for more details.

Full API

See zng_app::trace_recorder for the full API.

Structs

EventTrace

Represents a traced event.

ProcessTrace

Represents a single app process in a recorded trace.

ThreadTrace

Represents a single thread in an app process in a recorded trace.

Trace

Represents a recorded trace.

Functions

stop_recording

Stops recording and flushes.