API reference

@trace_event name [key=value...]
@trace_event name [key=value...] begin ... end

Record a Chrome trace event named name.

Keyword arguments are passed through to build_event, so cat, ph, ts, pid, tid, dur, args and friends may all be set.

In the first form a single event is emitted (an instant event, ph="i", unless you say otherwise). In the second form the given block is wrapped in a matching pair of "B"/"E" (begin/end) events, so the block shows up as a span in the trace viewer. The "E" event is emitted from a finally block, so spans are closed even if the body throws.

Examples

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

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

record_trace(name; kwargs...)

Build an event with build_event and append it to the global trace buffer. This is what @trace_event expands to; call it directly when the event's name or keywords are only known at runtime.

The event is dropped silently if the buffer is full.

build_event(name; kwargs...) -> Dict{String,Any}

Build a single Chrome trace event named name.

The standard fields are always present, defaulting as follows:

The optional fields dur, scope, cname, s, id, bp and metadata are copied through when supplied. args is normalized into a String-keyed Dict, and extra may be used to splat additional top-level keys into the event.

Example

ChromeTracing.build_event("work"; cat="compute", ph="X", dur=100)

save_trace(path) -> Int

Drain every buffered event and write them to path as a Chrome trace JSON array, returning the number of events written.

This is the one-shot counterpart to stream_trace: record events first, then dump them all at the end.

Example

@trace_event "work" cat="compute" begin
    sleep(0.01)
end
save_trace("trace.json")

stream_trace(path; capacity=DEFAULT_BUFFER_LIMIT,
             flush_interval=DEFAULT_STREAM_FLUSH_INTERVAL) -> StreamState

Open path for writing and start a background task that periodically flushes recorded events to it, returning the StreamState being used.

capacity sets how many events may be buffered between flushes; once the buffer is full, further events are dropped and counted in the returned state's dropped field. flush_interval is how long, in seconds, the writer sleeps between flushes.

If a stream is already running it is stopped and finalized first. Call stop_streaming! when you are done so the trace file is closed properly.

Example

stream = stream_trace("trace.json"; capacity=5000, flush_interval=0.05)
@trace_event "work" cat="compute" begin
    sleep(0.01)
end
stop_streaming!()
@info "dropped $(stream.dropped[]) events"

flush_trace!() -> Int

Immediately write any buffered events out to the file opened by stream_trace, without waiting for the background writer's next tick. Returns the number of events written, or 0 if streaming is not active.

The trace file is left open and unterminated; use stop_streaming! to finalize it.

stop_streaming!()

Stop the background writer started by stream_trace, flush any remaining buffered events, and finalize the trace file so that it is a valid JSON array.

clear_trace!()

Stop any in-progress streaming (finalizing the trace file, see stop_streaming!) and discard all buffered events.

Useful to get back to a known-empty state, e.g. between tests.

snapshot_default_buffer() -> Vector{Dict{String,Any}}

Drain and return every event currently buffered in the global trace buffer.

Note that this removes the events from the buffer; a second call immediately afterwards returns only whatever was recorded in between.

DEFAULT_BUFFER_LIMIT

Default maximum number of events buffered in memory at once. Once the ring buffer is full, newly recorded events are dropped and counted in StreamState.dropped rather than blocking the calling thread.

DEFAULT_STREAM_FLUSH_INTERVAL

Default number of seconds the background writer started by stream_trace sleeps between flushes of the buffered events.