NVIDIA Nsight Compute Collector#

Collection utilities for profiling Nsight Python runs using NVIDIA Nsight Compute (ncu).

This module contains logic for launching NVIDIA Nsight Compute with appropriate settings. NCU is instructed to profile specific code sections marked by NVTX ranges - the Nsight Python annotations.

class nsight.collection.ncu.NCUCollector( metrics: Sequence[str] = ['gpu__time_duration.sum'], ignore_kernel_list: Sequence[str] | None = None, combine_kernel_metrics: Callable[[float, float], float] | None = None, clock_control: Literal['base', 'none'] = 'none', cache_control: Literal['all', 'none'] = 'all', replay_mode: Literal['kernel', 'range'] = 'kernel', )#

Bases: NsightCollector

NCU collector for Nsight Python.

Parameters:

metrics (Sequence[str]) – Metrics to collect from NVIDIA Nsight Compute. By default we collect kernel runtimes in nanoseconds. A list of supported metrics can be found with ncu --list-metrics.
ignore_kernel_list (Optional[Sequence[str]]) – List of kernel names to ignore. If you call a library within a annotation context, you might not have precise control over which and how many kernels are being launched. If some of these kernels should be ignored in the Nsight Python profile, their their names can be blacklisted. Default: None
combine_kernel_metrics (Optional[Callable[[float, float], float]]) – By default, Nsight Python expects one kernel launch per annotation. In case an annotated region launches multiple kernels, instead of failing the profiling run, you can specify how to summarize the collected metrics into a single number. For example, if we profile runtime and want to sum the times of all kernels we can specify combine_kernel_metrics = lambda x, y: x + y. The function should take two arguments and return a single value. Default: None.
clock_control (Literal['base', 'none']) – Select clock_control option control in NVIDIA Nsight Compute. If None, we launch ncu --clock-control none .... For more details, see the NVIDIA Nsight Compute Profiling Guide: https://docs.nvidia.com/nsight-compute/ProfilingGuide/index.html#clock-control Default: None
cache_control (Literal['all', 'none']) – Select cache_control option control in NVIDIA Nsight Compute. If None, we launch ncu --cache-control none .... For more details, see the NVIDIA Nsight Compute Profiling Guide: https://docs.nvidia.com/nsight-compute/ProfilingGuide/index.html#cache-control Default: all
replay_mode (Literal['kernel', 'range']) – Select replay mode option control in NVIDIA Nsight Compute. If None, we launch ncu --replay-mode kernel .... For more details, see the NVIDIA Nsight Compute Profiling Guide: https://docs.nvidia.com/nsight-compute/ProfilingGuide/index.html#replay Default: kernel

collect( func: Callable[[...], None], configs: Iterable[Sequence[Any]], settings: ProfileSettings, )#

Collects profiling data using NVIDIA Nsight Compute.

Parameters:

func (Callable[..., None]) – The function to profile.
configs (Iterable[Sequence[Any]]) – iterable of configurations to run the function with.
settings (ProfileSettings) – Profiling settings.

Return type:

DataFrame | None

Returns:

Collected profiling data.

Raises:

exceptions.NCUNotAvailableError – Nsight Compute was not found on $PATH during import-time initialization (see try_init_injection()).
exceptions.ProfilerException – Injection could not be loaded or NVTX injection failed around the profiled region; the ncu attach process exited with an error; the profiled function or configs are invalid (see nsight.collection.core.run_profile_session()); or the report file was missing or could not be parsed (see nsight.extraction.extract_df_from_report()).
RuntimeError – Report extraction found no kernels, a mismatch in kernel counts, or several kernels in one annotation without combine_kernel_metrics (see nsight.extraction.extract_df_from_report()).
TypeError, ValueError – From report extraction if settings.derive_metric is not a valid callable or its signature does not match the metrics and config tuple.
exceptions.CoolingTimeoutError – If thermal throttling is enabled and the GPU does not reach the target headroom within thermal_timeout (see nsight.thermovision.ThermalController).

Note

Exceptions raised by func or by code it calls propagate to the caller unchanged.

class nsight.collection.ncu.NvInjResult(value)#

Bases: IntEnum

An enumeration.

NV_INJ_ERROR_INVALID_PARAMS = 2#

NV_INJ_ERROR_NOT_INITIALIZED = 3#

NV_INJ_ERROR_UNKNOWN = 1#

NV_INJ_SUCCESS = 0#

class nsight.collection.ncu.ProfilingParams#

Bases: Structure

pPriv#: Structure/Union member

structSize#: Structure/Union member

nsight.collection.ncu.begin_profiling()#

Return type:: None

nsight.collection.ncu.check_ncu_version(ncu_path: str)#

Raise ProfilerException if the installed ncu is older than MIN_NCU_VERSION.

Return type:: None
Parameters:: ncu_path (str)

nsight.collection.ncu.end_profiling()#

Return type:: None

nsight.collection.ncu.format_injection_error_message(code: int, action: str)#

Return type:

str

Parameters:

code (int)
action (str)

nsight.collection.ncu.get_injection_library_path(ncu_path: str)#

Return type:: str
Parameters:: ncu_path (str)

nsight.collection.ncu.launch_ncu( report_path: str, metrics: Sequence[str], cache_control: Literal['none', 'all'], clock_control: Literal['none', 'base'], replay_mode: Literal['kernel', 'range'], verbosity: VerbosityLevel, )#

Launch NVIDIA Nsight Compute to profile the current script with specified options.

Parameters:

report_path (str) – Path to write report file to.
metrics (Sequence[str]) – Specific metrics to collect.
cache_control (Literal['none', 'all']) – Select cache control option
clock_control (Literal['none', 'base']) – Select clock control option
replay_mode (Literal['kernel', 'range']) – Select replay mode option
verbosity (VerbosityLevel) – Controls output verbosity. SILENT disables NCU logs (--quiet), which reduces detail in ProfilerException on failure. DEBUG prints the NCU command and enables --verbose NCU output.

Raises:

ValueError – If invalid values are provided for cache_control, clock_control, or replay_mode.

Return type:

tuple[Popen[Any], str, str]

Note

The attach command uses the ncu name on $PATH (no resolved full path). Whether NCU is usable is determined in try_init_injection() at import; NCUCollector.collect raises if the CLI was not found.

Return type:

tuple[Popen[Any], str, str]

Returns:

path to the NVIDIA Nsight Compute log file Produces NVIDIA Nsight Compute report file with profiling data.

Parameters:

report_path (str)
metrics (Sequence[str])
cache_control (Literal['none', 'all'])
clock_control (Literal['none', 'base'])
replay_mode (Literal['kernel', 'range'])
verbosity (VerbosityLevel)

nsight.collection.ncu.load_library(path: str)#

Load the injection shared library.

Return type:: CDLL
Parameters:: path (str)

nsight.collection.ncu.try_init_injection()#

Load the injection library callables, or set injection_load_error on failure.

Return type:: None