profiler_command#

Profiler command wrappers for different profilers (Unitrace, NCU, VTune)

Functions

get_profilers(language, arch[, profiler_type])

Get the appropriate profiler class based on user-specified profiler type or language & GPU architecture.

Classes

`NCU`(output_dir[, ncu_cmd])	Nsight Compute profiler helper
`OCLUnitrace`(output_dir[, group, timeline, ...])	Helper to run Unitrace for OpenCL kernels with metric-sampling
`Profiler`(output_dir)	Abstract base class for profiler helpers
`Unitrace`(output_dir[, group, timeline, ...])	Unitrace profiler helper
`VTune`(output_dir[, vtune_cmd])	VTune profiler helper for Intel GPUs

Exceptions

ProfilerUnavailable

Exception if profiler cannot be found

exception kernelfoundry.eval_pipeline.profiler_command.ProfilerUnavailable[source]#: Exception if profiler cannot be found

class kernelfoundry.eval_pipeline.profiler_command.Profiler(output_dir: Path | str)[source]#

Abstract base class for profiler helpers

__init__(output_dir: Path | str)[source]#

abstract property name: str#: Return the name of the profiler

unavailable_reason() → str | None[source]#: Why this profiler cannot run on this machine, or None if nothing rules it out.

abstract wrap_cmd(cmd: str) → str[source]#

Wrap the given command with profiler-specific command :param cmd: The original command to run the program without profiling

Returns:: A wrapped command that includes the original command and any additional commands needed for profiling.

env_vars()[source]#: Return a dictionary of environment variables to update or add when running the command

end_marker() → str | None[source]#

Return the end-of-process marker string for this profiler.

The marker is passed to robust_subprocess_run to detect when the profiled process has finished and can safely be terminated.

The default "pytest" activates the pytest-summary monitor, which waits for the pytest result line. Return a different string to watch for that literal in the output, or None to disable early termination entirely.

prepare(host_output_dir: Path) → None[source]#: Prepare the host output directory before running the profiler command. Override in subclasses that need to stage files into the host directory (e.g. scripts that must be accessible inside a container).

abstract read_output() → dict[str, str][source]#: Read the profiler output into a dictionary that maps the filename to its content

class kernelfoundry.eval_pipeline.profiler_command.Unitrace(output_dir: Path | str, group: str = 'ComputeBasic', timeline: bool = True, unitrace_cmd: str = 'unitrace')[source]#

Unitrace profiler helper

__init__(output_dir: Path | str, group: str = 'ComputeBasic', timeline: bool = True, unitrace_cmd: str = 'unitrace')[source]#

property name: str#: Return the name of the profiler

wrap_cmd(cmd: str) → str[source]#: Wrap the given command with unitrace profiling command

env_vars()[source]#: Return a dictionary of environment variables to update or add when running the command

read_output() → dict[str, str][source]#: Read the profiler output into a dictionary that maps the filename to its content

class kernelfoundry.eval_pipeline.profiler_command.OCLUnitrace(output_dir: Path | str, group: str = 'ComputeBasic', timeline: bool = True, unitrace_cmd: str = 'unitrace')[source]#

Helper to run Unitrace for OpenCL kernels with metric-sampling

end_marker() → str | None[source]#

Return the end-of-process marker string for this profiler.

The marker is passed to robust_subprocess_run to detect when the profiled process has finished and can safely be terminated.

prepare(host_output_dir: Path) → None[source]#: Copy the retry script into the host output directory so it is accessible inside the container (where host_output_dir is mounted as self.output_dir).

wrap_cmd(cmd: str) → str[source]#: Wrap the given command with unitrace profiling command for OpenCL using retry script

class kernelfoundry.eval_pipeline.profiler_command.NCU(output_dir: Path | str, ncu_cmd: str = 'ncu')[source]#

Nsight Compute profiler helper

__init__(output_dir: Path | str, ncu_cmd: str = 'ncu')[source]#

property name: str#: Return the name of the profiler

unavailable_reason() → str | None[source]#: Why this profiler cannot run on this machine, or None if nothing rules it out.

wrap_cmd(cmd: str) → str[source]#

Wrap the given command with NCU profiling command.

ncu needs elevated privileges to read performance counters unless the driver has been told to allow it for all users. Since sudo is disabled on Windows, the command is issued plainly: it succeeds where counter access has been granted, and where it has not, read_output explains what to do.

See https://developer.nvidia.com/nvidia-development-tools-solutions-err_nvgpuctrperm-permission-issue-performance-counters for how to enable non-root profiling on either platform.

read_output() → dict[str, str][source]#: Read the profiler output into a dictionary that maps the filename to its content

class kernelfoundry.eval_pipeline.profiler_command.VTune(output_dir: Path | str, vtune_cmd: str = 'vtune')[source]#

VTune profiler helper for Intel GPUs

__init__(output_dir: Path | str, vtune_cmd: str = 'vtune')[source]#

property name: str#: Return the name of the profiler

wrap_cmd(cmd: str) → str[source]#

Wrap the given command with VTune collection and hotspot report generation.

Chains two commands with && so all vtune invocations happen inside the same environment (e.g. container) where vtune is available:

vtune -collect (paused; the kernel under test resumes it via ITT)
vtune -report hotspots -> tsv file

read_output() then simply reads that file without invoking vtune.

end_marker() → str | None[source]#

Return the end-of-process marker string for this profiler.

The marker is passed to robust_subprocess_run to detect when the profiled process has finished and can safely be terminated.

env_vars()[source]#: Return a dictionary of environment variables to update or add when running the command

read_output() → dict[str, str][source]#

Read the pre-generated TSV report and return a counters JSON.

The TSV file was written by the vtune -report command chained in wrap_cmd, so no vtune invocation is needed here.

kernelfoundry.eval_pipeline.profiler_command.get_profilers(language: str, arch: str, profiler_type: str | None = None) → list[type[Profiler]][source]#: Get the appropriate profiler class based on user-specified profiler type or language & GPU architecture.