PerfCheckerMakie public API
This reference renders the actual Julia docstrings of PerfCheckerMakie 1.0.4 with Core from the selected source revision, including the exported observation_plot model for diagnostic axes. The WGLMakie/Bonito extension is loaded to document its real HTML method. Documentation generation does not render a figure or start a server.
The full API is the canonical reference. Full API also includes documented internal bindings.
PerfCheckerMakie.PerfCheckerMakie Module
Makie figures for PerfChecker results and presentation models. Load WGLMakie to activate HTML rendering, or a Makie display/export backend for static figures. Saved-result rendering does not install a renderer in measurement workers.
sourcePerfChecker.checkres_to_boxplots Method
checkres_to_boxplots(result, Val(:benchmark); kwarg=:times, figure_kwargs=(;), axis_kwargs=(;), plot_kwargs=(;))Render finite saved samples from the selected table column as version boxplots. Values retain their collector units: :times and :gctimes are nanoseconds, :memory is bytes, and :allocs is an allocation count. Empty or entirely nonfinite columns produce a labeled Makie Figure; missing columns raise the normal property access error. The subtitle names BenchmarkTools and shows tags. Attribute bundles target Figure, Axis and boxplot respectively; version labels default to pi/2. No workload is executed or file written.
PerfChecker.checkres_to_boxplots Method
Render finite Chairmarks version distributions from kwarg (default :times). Accept explicit Figure, Axis and boxplot attribute bundles. Empty/nonfinite samples produce a labeled Figure; collector units, title and tags are retained. :times is seconds, :gctimes is GC fraction, :bytes is allocated bytes, and :allocs is an allocation count. Values are not converted between collectors. Version labels default to pi/2. Rendering neither measures nor writes files.
PerfChecker.checkres_to_pie Method
Return version-name/Figure pairs for saved allocation tables, retaining result tags and package/version names. Keywords go to table_to_pie; no measurement or export occurs. Empty tables retain a labeled Figure in the collection.
PerfChecker.checkres_to_scatterlines Method
Render saved allocated bytes aggregated by file across versions. Missing files remain gaps, not zero observations; nonfinite entries are excluded. Accept explicit Figure, Axis and scatterlines attributes and an optional title. Version ticks default to pi/2, with collector and result tags visible. Return a labeled Figure for empty evidence. No measurement or file export occurs.
sourcePerfChecker.checkres_to_scatterlines Method
checkres_to_scatterlines(result, Val(:benchmark); figure_kwargs=(;), axis_kwargs=(;), plot_kwargs=(;))Render each saved metric's finite version minima relative to its finite minimum across versions. Equal zeros display at one; a nonzero value over zero or an absent sample is a gap. NaN and Inf are excluded before finding minima. Return a Makie Figure, including a labeled figure when no finite metric exists. The subtitle names BenchmarkTools and shows result tags. Version ticks are vertical by default. Explicit Figure, Axis and scatterlines attribute bundles override presentation defaults without rerunning measurements.
sourcePerfChecker.checkres_to_scatterlines Method
Render finite Chairmarks metric minima as normalized version curves. Accept the same Figure, Axis and scatterlines attribute bundles and zero/missing-sample semantics as checkres_to_scatterlines(result, Val(:benchmark)). Title and subtitle retain the Chairmarks collector and result tags. No workload is rerun.
PerfChecker.performance_figure Method
performance_figure(plot; figure_kwargs=(;), axis_kwargs=(;), plot_kwargs=(;), tags=nothing, tool=nothing)Render saved evidence with the active Makie backend. Attribute bundles are NamedTuples or Symbol-keyed dictionaries: figure attributes go to Figure, axis attributes customize the completed Axis, and plot attributes override the primary recipe (lines, scatterlines, boxplot, barplot, pie or heatmap). Inspection overlays and reference lines keep their own settings. Attributes are presentation only; no workload is run or measurement changed. Unknown Makie attributes raise Makie's normal error. Collector and tags appear in the subtitle; pass tool explicitly for manually built models whose collector identity is absent. Collector names and tag lists are appended to customized subtitles while titles are preserved. Empty evidence returns a labeled figure. Allocation pies draw strictly positive weights; an all-zero recorded model returns a "No positive allocation weight" figure without dividing by a zero total. Normalized models can set plot.options["xlabel"] to label their target axis (default "package version"), for example "Implementation" for measured implementations. This changes presentation only, preserving ratios and values.
PerfChecker.saveplot Method
saveplot(path, figure::Makie.Figure; overwrite=false, kwargs...) -> String
saveplot(directory, named_figures; format=:svg, overwrite=false, kwargs...) -> Vector{String}Export existing figures using the active Makie backend. Load CairoMakie for SVG/PNG output. Single-file paths must end in .svg or .png; their parent directory must exist. The collection overload creates its explicit directory, sanitizes names into portable filename components and rejects collisions (including case-insensitive collisions) before writing. It accepts the pairs returned by checkres_figures or an explicit collection of name/figure pairs. Existing files and symlinks are preserved unless overwrite=true; directories are never replaced. All destinations are checked before a collection is exported. Rendering uses a temporary file in the destination filesystem and cleans it up on failure; failures can leave earlier completed collection files. Additional keywords go to Makie's save, for example px_per_unit=2 for PNG. Return absolute paths. No workload is rerun; provenance remains in the saved result rather than being inferred from an image.
PerfChecker.suite_dashboard Method
suite_dashboard(result; view=:normalized, figure_kwargs=(;), axis_kwargs=(;), plot_kwargs=(;))Render saved suite results without running measurements. The normalized view uses the standard saved-evidence model when available. The absolute view shows minimum elapsed time in seconds: BenchmarkTools nanoseconds are converted only for display, while Chairmarks seconds are retained. Unknown collector units are excluded with a visible explanation, never inferred from magnitude. Source tables and summaries remain unchanged. Titles name the displayed collectors; subtitles retain result tags. Explicit attribute bundles customize presentation.
sourcePerfChecker.table_to_pie Method
table_to_pie(table, Val(:alloc); pkg_name="", tags=nothing, min_percentage=5, top=40,
figure_kwargs=(;), axis_kwargs=(;), plot_kwargs=(;))Render positive finite allocation bytes by source location, grouping sites below the share threshold and capping legend entries with top. Tables use filename/ line (or filenames/linenumbers) and bytes columns. Empty or zero-only evidence returns a labeled Figure. Explicit attribute bundles target Figure, Axis and pie; the title names Julia allocation tracking and the subtitle lists tags. This reads saved bytes without rerunning a check or writing an image.
PerfCheckerMakie.checkres_figures Method
checkres_figures(result, Val(backend); kinds=nothing, metrics=nothing, figure_kwargs=(;),
axis_kwargs=(;), plot_kwargs=(;))Collect named Makie figures from saved CheckerResult tables. backend is :alloc, :benchmark or :chairmark. kinds selects :trajectory, :distribution (timing collectors) or :pie (allocations). Defaults select all applicable kinds, in that order. Distributions default to four metrics: BenchmarkTools :times, :gctimes, :memory, :allocs; Chairmarks :times, :gctimes, :bytes, :allocs. The duplicate :bytes_or_memory alias is omitted. Pass metrics to select a distinct subset for distributions; selected columns must exist in every saved table. Metrics cannot be supplied for an allocation collector or a selection without distributions. Empty, duplicated, missing or unsupported selections raise ArgumentError before rendering. No checks are rerun and no files are written. Names include each distribution's metric as well as the collector, package, version and tags; allocation pies retain one figure per version. Presentation attributes use the same explicit bundles as performance_figure. Use saveplot to export this collection to an explicit directory.
PerfCheckerMakie.observation_plot Method
observation_plot(id, rows; title, panels, collector, scope, description="", metadata=Dict())Build a saved-evidence plot with explicit axes rather than package-version axes. Use this for request sizes, operation indices, implementation names, startup phases or native-profiler timelines. No measurement is run and no file is written. Render the returned PerfChecker.PerformancePlot with performance_figure, or load WGLMakie and call PerfChecker.performance_plot_html for an interactive export.
panels is a nonempty vector of dictionaries. Each panel requires a unique id, title, xlabel, xunit, ylabel, unit and xkind ("numeric" or "categorical"). A categorical panel also requires an ordered, distinct categories vector. Optional yscale is "linear" (default) or "log10". Units are supplied explicitly, including "" for a categorical axis; neither units nor package versions are inferred from values or labels.
Each row requires panel, series, x and value. x must match its panel's axis. value is finite numeric evidence, or nothing/missing for an unavailable observation. Unavailable rows remain in the model and inspector but have no mark; zero is never substituted. Logarithmic panels require strictly positive values. Optional label adds context, version records a real package version, and style selects "scatter" (default), "line", "scatterline" or "bar". Bars require a linear y-axis so that their zero baseline remains meaningful. Rows in a series/version group must use the same style. Lines follow recorded row order; callers must supply meaningful order rather than imply a time axis.
collector names the actual tool. scope states what was measured, for example "one loopback process; application bytes are not wire bytes". metadata retains explicit provenance such as source SHA-256 and run IDs. Inputs are deep-copied. The interactive view filters panels, series and recorded versions without changing observations, inspects exact rows and downloads the complete model.
Example
The values in this minimal example are illustrative. Replace them with your recorded observations and attach their provenance in metadata for publication.
using PerfChecker, PerfCheckerMakie, WGLMakie
panels = [Dict("id" => "time", "title" => "Warm requests",
"xlabel" => "Request body", "xunit" => "By", "ylabel" => "Round trip",
"unit" => "s", "xkind" => "numeric")]
rows = [Dict("panel" => "time", "series" => "Oxygen 1.11.0",
"x" => 4096, "value" => 0.002, "label" => "Illustrative sample")]
model = observation_plot("request-time", rows; title = "Recorded request",
panels, collector = "PerfChecker network runner", scope = "Loopback only")
html = performance_plot_html(model)Optional WGLMakie method
This method belongs to a Core binding and is defined by the loaded Makie companion extension. Its docstring is rendered from that extension, not copied from Core.
PerfChecker.performance_plot_html Method
performance_plot_html(plot; asset_directory=nothing, html_directory=nothing)Render an interactive HTML document from a recorded plot. By default, the document contains its assets and can be saved as a standalone file.
To share WGL assets between several documents, pass both asset_directory (the directory where Bonito writes assets) and html_directory (the directory where the returned HTML will be saved). Links are relative to html_directory; deploy or move the HTML and asset directories together, preserving their relative layout. This function returns HTML without writing an HTML file or creating its directory. For normalized models, plot.options["xlabel"] labels the target axis (default "Package version") and plot.options["target_label"] labels selectors and the recorded-target table (default "version"). For example, set these to "Implementation" and "implementation" for measured implementations; target identities remain in the model's version field and numeric values are unchanged. Shared-asset exports bypass the standalone HTML cache. Normalized plots, flame graphs and observation series already use compact standalone HTML and do not write shared assets. Observation series retain their explicit axes, units and provenance, with panel/series/version filters and exact recorded-point inspection.
Normalized measurements provide metric visibility, selection of recorded versions, viewport zoom and pan, exact point inspection, and SVG/CSV export. Selection preserves the original ratios. WGL figures provide viewport zoom and pan. Series, distributions, deltas, tradeoffs and allocation line/file/heatmap/pie views include an exact recorded-row index and JavaScript popups on native mark clicks. Zero-byte allocation rows remain in the index even when their bars or pie sectors have no clickable surface. An all-zero pie provides its recorded-row readout without a fabricated sector or highlight. Flame graphs preserve exact recorded widths and share native diagnostic colors. Their numeric frame index, keyboard focus and pointer inspection retain complete paths and values, including frames too thin to click. They provide viewport zoom/pan/Fit and original-model JSON and SVG-view downloads. Julia DataInspector and ordinary Makie axis zoom callbacks are not exported.
source