ChromeTracing.jl

ChromeTracing.ChromeTracing — Module

ChromeTracing

Lightweight tracing for Julia programs, emitting Chrome trace event JSON files. See: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU

Events are recorded with the @trace_event macro into a lock-free ring buffer, and are then either dumped all at once with save_trace or streamed to disk in the background with stream_trace.

The resulting JSON file can be loaded into chrome://tracing or dragged into the perfetto web UI.

Example

using ChromeTracing

stream_trace("trace.json"; flush_interval=0.05)

@trace_event "startup" cat="app" args=Dict("msg" => "boot")

@trace_event "work" cat="compute" begin
    sleep(0.01)
end

stop_streaming!()  # flushes and finalizes trace.json

source

Recording events

Events are recorded with the @trace_event macro. In its single-argument form it emits an instant event; given a trailing begin ... end block it wraps the block in a matching pair of begin/end events, which the trace viewer renders as a span:

using ChromeTracing

@trace_event "startup" cat="app" args=Dict("msg" => "boot")

@trace_event "work" cat="compute" begin
    sleep(0.01)
end

Any keyword accepted by build_event may be passed to @trace_event, including cat, ph, ts, pid, tid, dur and args.

One-shot Saving: `save_trace`

Record everything into the in-memory buffer, then dump it at the end:

@trace_event "work" cat="compute" begin
    sleep(0.01)
end

save_trace("trace.json")

Streaming: `stream_trace`

For long-running programs, start a background writer that periodically flushes buffered events to disk. Call stop_streaming! when you are done so the file is finalized into a valid JSON array:

stream_trace("trace.json"; capacity=5000, flush_interval=0.05)

@trace_event "work" cat="compute" begin
    sleep(0.01)
end

stop_streaming!()

flush_trace! forces a flush without waiting for the next tick, and clear_trace! discards everything buffered so far.

Dropped events

The event buffer is a fixed-size, lock-free ring buffer. When producers outrun the writer and the buffer fills up, new events are dropped rather than blocking the calling thread, which keeps tracing overhead bounded. The number of dropped events is available on the state returned by stream_trace:

stream = stream_trace("trace.json")
# ... work ...
stop_streaming!()
@info "dropped $(stream.dropped[]) events"

Raise capacity or lower flush_interval if you are dropping more than you can afford.

Viewing the trace

Open the resulting JSON file in chrome://tracing, or drag and drop it into perfetto.

Running the packaged example

julia --threads=auto --project=. example.jl