scope_profiler.native_samples

Line-level profiles of native (C) regions, from the sampler’s .sps files.

With sampling on (sp_start_sampling() or SCOPE_PROFILER_SAMPLE_HZ), the C library records the interrupted instruction address and the innermost open region at every timer tick, and sp_finalize() writes them to <prefix>_rank<NNNNN>.sps next to the trace. This module reads that file and maps the addresses to file:line using the program’s debug info (build with -g), so the work happens after the run, not in it.

Layout, native byte order, as written by sp_finalize::

char[8]   "SCOPESMP"
int32     format version (1)
int32     rank
int32     sampling rate [Hz]
int64     timer ticks in total, whether or not they landed in a region
int32     number of regions
per region:  int32 name length, char[] name
int32     number of modules
per module:  int32 path length, char[] path, uint64 load address
int64     number of samples
per sample:  int32 region, int32 module (-1 if unknown), uint64 address

Attributes

Name	Description
KNOWN_FORMAT_VERSIONS	No description.
MAGIC	No description.
SAMPLES_SUFFIX	No description.

Classes

Name	Description
LineStat	Samples attributed to one source line of one region.
SampleFile	One rank's raw samples.
SampleFormatError	A file is not a scope-profiler sample file, or is truncated.
SymbolizerError	No tool is available to map addresses to source lines.

Functions

Name	Description
find_sample_files	Collect .sps files from paths, directories, or a mix of both.
format_line_profile	Render :func:line_profile output as plain-text tables.
line_profile	Aggregate a rank's samples into per-line statistics for each region.
read_samples	Read one .sps file written by sp_finalize().
symbolize	Map absolute addresses in one module to (function, file, line).

KNOWN_FORMAT_VERSIONSattributemodule attribute#

View source

KNOWN_FORMAT_VERSIONS = (1)

MAGICattributemodule attribute#

View source

MAGIC = b'SCOPESMP'

SAMPLES_SUFFIXattributemodule attribute#

View source

SAMPLES_SUFFIX = '.sps'

LineStatclassdataclass#

View source

class LineStat(file: str, line: int, function: str, samples: int)

Samples attributed to one source line of one region.

fileattributeinstance attribute#

View source

file: str

functionattributeinstance attribute#

View source

function: str

lineattributeinstance attribute#

View source

line: int

samplesattributeinstance attribute#

View source

samples: int

SampleFileclassdataclass#

View source

class SampleFile(rank: int, hz: int, ticks: int, regions: list, modules: list, samples: np.ndarray)

One rank’s raw samples.

hzattributeinstance attribute#

View source

hz: int

modulesattributeinstance attribute#

View source

modules: list

rankattributeinstance attribute#

View source

rank: int

regionsattributeinstance attribute#

View source

regions: list

samplesattributeclass attributeinstance attribute#

View source

samples: np.ndarray = field(repr=False)

ticksattributeinstance attribute#

View source

ticks: int

SampleFormatErrorclass#

View source

class SampleFormatError(ValueError)

Bases: ValueError

A file is not a scope-profiler sample file, or is truncated.

SymbolizerErrorclass#

View source

class SymbolizerError(RuntimeError)

Bases: RuntimeError

No tool is available to map addresses to source lines.

find_sample_filesfunction#

View source

def find_sample_files(inputs) -> list

Collect .sps files from paths, directories, or a mix of both.

format_line_profilefunction#

View source

def format_line_profile(profile: dict, top: int = 10, source: bool = True) -> str

Render :func:line_profile output as plain-text tables.

line_profilefunction#

View source

def line_profile(samples: SampleFile) -> dict

Aggregate a rank’s samples into per-line statistics for each region.

Returns

dict {region name: [LineStat, ...]}, hottest line first. Counts are samples of the line itself; code without debug info (a library such as libm) is grouped under ??:0. The timer’s effective rate can be below the requested one, so shares are reported rather than seconds.

read_samplesfunction#

View source

def read_samples(path) -> SampleFile

Read one .sps file written by sp_finalize().

Raises

SampleFormatError If the file is not a sample file, is truncated, or is of a newer format version.

symbolizefunction#

View source

def symbolize(module: str, base: int, addresses: list) -> list

Map absolute addresses in one module to (function, file, line).

Needs the program built with -g; without debug info the line is 0.