scope_profiler.speedscope_export

Export merged HDF5 profiling data to the speedscope JSON format.

A speedscope file is a single JSON document holding a table of frames and one or more profiles referring to it. The profiles written here are evented: each call contributes an open (O) and a close (C) event carrying a timestamp, which preserves every individual call rather than the aggregate a .prof file keeps. Drop the file on https://www.speedscope.app to view it.

Regions carry no call graph of their own, so the caller/callee relations are reconstructed from timestamp containment - the same reconstruction the flame chart and the .prof export use (:func:~scope_profiler.call_stack.build_call_arrays).

An evented profile is two events per call, so the output is inherently proportional to the run. The reconstruction feeding it is not: it arrives as columns, and only the events themselves are ever built as dicts.

Attributes

Name	Description
NS_PER_SECOND	No description.
SCHEMA_URL	No description.
TIME_UNIT	No description.

Functions

Name	Description
build_speedscope_document	Build a full speedscope document holding one profile per entry.
build_speedscope_profile	Build one evented speedscope profile from reconstructed calls.
export_speedscope	Write speedscope JSON files for the selected ranks.
write_speedscope_file	Write a speedscope document to filepath as JSON.

NS_PER_SECONDattributemodule attribute#

View source

NS_PER_SECOND = 1000000000.0

SCHEMA_URLattributemodule attribute#

View source

SCHEMA_URL = 'https://www.speedscope.app/file-format-schema.json'

TIME_UNITattributemodule attribute#

View source

TIME_UNIT = 'seconds'

build_speedscope_documentfunction#

View source

def build_speedscope_document(named_calls: Sequence[tuple[str, CallArrays]], name: str) -> dict

Build a full speedscope document holding one profile per entry.

Parameters

named_calls : sequence of (str, CallArrays) Profile name and calls for each profile to include, e.g. one per rank. name : str Name of the document, shown in speedscope’s title bar.

Returns

dict The document, ready to be serialized as JSON.

build_speedscope_profilefunction#

View source

def build_speedscope_profile(calls: CallArrays, name: str, frame_indices: dict[str, int], frames: list[dict], origin: float = 0.0) -> dict

Build one evented speedscope profile from reconstructed calls.

Parameters

calls : CallArrays Calls as returned by :func:~scope_profiler.call_stack.build_call_arrays. Their intervals are properly nested, which is exactly what an evented profile needs: a frame can only close while it is on top of the stack. name : str Name of the profile, shown in speedscope’s profile selector. frame_indices, frames : dict, list The document-wide frame table, extended in place: speedscope shares one table across all profiles in a file, so profiles of the same run refer to the same frames. origin : float, optional Subtracted from every timestamp. Timestamps come from perf_counter_ns and are large in absolute terms; rebasing them on a common origin keeps the values readable (and precise) without shifting profiles relative to each other.

Returns

dict A profile object as described by the speedscope file format schema.

export_speedscopefunction#

View source

def export_speedscope(profiling_data: ProfilingResults | Sequence[ProfilingResults], filepath: str | Path, ranks: list[int] | int | None = None, include: list[str] | str | None = None, exclude: list[str] | str | None = None, verbose: bool = True) -> list[Path]

Write speedscope JSON files for the selected ranks.

One file is written per input HDF5 file, holding one profile per rank --- or, for a run profiled with track_threads, one per thread and task. Unlike .prof, the format carries several profiles per file, and speedscope switches between them from its profile selector.

Parameters

profiling_data : ProfilingResults | Sequence[ProfilingResults] The run(s) to export: file runs, in-memory results from ProfileManager.finalize(return_results=True), or a mix. filepath : str | Path Base output path, e.g. figures/profile.speedscope.json. The input file’s stem is appended when more than one file is exported. ranks : list[int] | int, optional Ranks to export (default: rank 0 only). include, exclude : list[str] | str, optional Region name filters, as for the plotting functions.

Returns

list[Path] The files written, in the order they were written.

write_speedscope_filefunction#

View source

def write_speedscope_file(filepath: str | Path, document: dict) -> Path

Write a speedscope document to filepath as JSON.