API reference
Exported
ProfilePerfetto.@perfetto — Macro
@perfetto expr [key=value ...]Profile expr and render the result as an interactive Perfetto flame chart, inline in a Pluto, VS Code, or Jupyter notebook.
The sampling rate is calibrated automatically: expr is run a few times, starting at a coarse 10 ms sampling delay, and the delay is sharpened on each round so the final, displayed run captures plenty of detail without spending all its time inside the sampler. You don't have to pick a delay by hand.
Because of the calibration loop, expr is evaluated several times (up to max_rounds, default 6). Don't use @perfetto on code with observable side effects (mutating shared state, writing files, sending network requests, …) — wrap the workload in something idempotent first, or call perfetto_view on profile data you collected yourself.
Calibration options
Trailing key = value arguments tune the calibration loop:
initial_delay::Float64(default0.01, i.e. 10 ms) — sampling delay used for the first calibration round. The first round is meant to be coarse and cheap; it just measures how longexprtakes.min_delay::Float64(default1e-7, i.e. 0.1 μs) — hard floor on the sampling delay. Raise it if you see huge profile overhead on very fast workloads.buffer_slots::Int(default10_000_000, ~80 MB) — size of the profile sample buffer. The loop targets ~50 % fill; bump this if traces get truncated.max_rounds::Int(default6) — maximum number of timesexpris run. Lower this if you want fewer repetitions.max_inflation::Float64(default10.0) — largest allowed ratio of measured wall time to the overhead-free baseline. Calibration backs off the sampling delay so profiler overhead can't blow runtime up by more than this factor.max_step::Float64(default8.0) — maximum factor by which the delay is allowed to shrink between consecutive rounds.
Example
using ProfilePerfetto
@perfetto my_expensive_function(args...)
# Cap calibration at 4 rounds and don't sharpen below 10 μs:
@perfetto my_expensive_function(args...) max_rounds=4 min_delay=1e-5See also @perfetto_open for opening the chart in a browser, and perfetto_view / perfetto_open for visualizing profile data you collected yourself.
ProfilePerfetto.@perfetto_view — Macro
@perfetto expr [key=value ...]Profile expr and render the result as an interactive Perfetto flame chart, inline in a Pluto, VS Code, or Jupyter notebook.
The sampling rate is calibrated automatically: expr is run a few times, starting at a coarse 10 ms sampling delay, and the delay is sharpened on each round so the final, displayed run captures plenty of detail without spending all its time inside the sampler. You don't have to pick a delay by hand.
Because of the calibration loop, expr is evaluated several times (up to max_rounds, default 6). Don't use @perfetto on code with observable side effects (mutating shared state, writing files, sending network requests, …) — wrap the workload in something idempotent first, or call perfetto_view on profile data you collected yourself.
Calibration options
Trailing key = value arguments tune the calibration loop:
initial_delay::Float64(default0.01, i.e. 10 ms) — sampling delay used for the first calibration round. The first round is meant to be coarse and cheap; it just measures how longexprtakes.min_delay::Float64(default1e-7, i.e. 0.1 μs) — hard floor on the sampling delay. Raise it if you see huge profile overhead on very fast workloads.buffer_slots::Int(default10_000_000, ~80 MB) — size of the profile sample buffer. The loop targets ~50 % fill; bump this if traces get truncated.max_rounds::Int(default6) — maximum number of timesexpris run. Lower this if you want fewer repetitions.max_inflation::Float64(default10.0) — largest allowed ratio of measured wall time to the overhead-free baseline. Calibration backs off the sampling delay so profiler overhead can't blow runtime up by more than this factor.max_step::Float64(default8.0) — maximum factor by which the delay is allowed to shrink between consecutive rounds.
Example
using ProfilePerfetto
@perfetto my_expensive_function(args...)
# Cap calibration at 4 rounds and don't sharpen below 10 μs:
@perfetto my_expensive_function(args...) max_rounds=4 min_delay=1e-5See also @perfetto_open for opening the chart in a browser, and perfetto_view / perfetto_open for visualizing profile data you collected yourself.
ProfilePerfetto.@perfetto_open — Macro
@perfetto_open expr [key=value ...]Like @perfetto, but opens the resulting flame chart in your default web browser instead of rendering inline. Use this from the plain Julia REPL.
The expression is executed multiple times as part of automatic sampling rate calibration; see @perfetto for details and for the list of accepted key = value calibration options.
ProfilePerfetto.perfetto_view — Function
perfetto_view(data = Profile.fetch(; include_meta = false),
lidict = Profile.getdict(data);
name = "Julia profile")Converts Julia profile sample data to an embedded Perfetto trace viewer. Returns a PerfettoDisplay that renders as an interactive trace when displayed in a Pluto, VS Code or Jupyter notebook cell.
See also: @perfetto, perfetto_open.
ProfilePerfetto.perfetto_open — Function
perfetto_open(data = Profile.fetch(; include_meta = false),
lidict = Profile.getdict(data);
name = "Julia profile")Opens the current Julia profile in the default web browser using the Perfetto trace viewer. Returns the path to the temporary HTML file that was opened.
ProfilePerfetto.perfetto_json — Function
perfetto_json(data = Profile.fetch(; include_meta = true),
lidict = Profile.getdict(data);
filter_sentinel = false,
wall_time_ns = nothing)Convert Julia profile sample data to a Perfetto trace-event JSON string and return it as a String. Useful for saving the trace to a file or piping it to another tool.
See also: perfetto_view, perfetto_open.
ProfilePerfetto.PerfettoDisplay — Type
PerfettoDisplayReturned by perfetto_view. Renders as an embedded Perfetto trace viewer when displayed in a Pluto, VS Code or Jupyter notebook cell.