scope_profiler.region
Data container for a single profiling region loaded from HDF5.
Attributes
| Name | Description |
|---|---|
NS_PER_SECOND | No description. |
Classes
| Name | Description |
|---|---|
EventDataUnavailableError | Raised when a summary-only result is asked for per-call event data. |
Region | Timing data for one region on one rank. |
NS_PER_SECONDattributemodule attribute#
NS_PER_SECOND = 1000000000.0EventDataUnavailableErrorclass#
class EventDataUnavailableError(RuntimeError)Bases: RuntimeError
Raised when a summary-only result is asked for per-call event data.
Regionclass#
class Region(start_times: np.ndarray, end_times: np.ndarray, gpu_durations: np.ndarray | None = None, call_ids: np.ndarray | None = None, parent_ids: np.ndarray | None = None, thread_ids: np.ndarray | None = None, task_ids: np.ndarray | None = None, await_times: np.ndarray | None = None, event_metadata: list[dict] | tuple[dict, ...] | None = None, source_file: str | None = None, source_lineno: int | None = None, source_text: str | None = None, tags=(), aggregate: dict | None = None, event_data_available: bool = True)Timing data for one region on one rank.
All duration and timestamp properties are reported in seconds; the underlying HDF5 data is stored in nanoseconds.
average_durationproperty#
average_duration: floatAverage duration per call in seconds.
await_timesproperty#
await_times: np.ndarray | NoneSeconds each call spent with its task suspended, or None.
The wall time inside the with block during which the task was not
running: awaiting, or switched away from. Subtracting it from the
call’s duration leaves the time the lane actually held its thread.
await_times_nsproperty#
await_times_ns: np.ndarray | NoneNanoseconds each call spent with its task suspended, or None.
call_idsproperty#
call_idsExplicit call ids, or None for legacy profiles.
durationsproperty#
durations: np.ndarrayDuration of all calls in seconds.
durations_nsproperty#
durations_ns: np.ndarrayDuration of all calls in nanoseconds, as integers.
end_timesproperty#
end_times: np.ndarrayEnd times of all calls in seconds.
end_times_nsproperty#
end_times_ns: np.ndarrayEnd times of all calls in nanoseconds, exactly as stored.
event_metadataproperty#
event_metadata: tuple[dict, ...]Per-call scoped metadata, aligned with the event arrays.
exclusive_durationproperty#
exclusive_duration: floatAlias for :attr:total_exclusive_duration.
exclusive_durationsproperty#
exclusive_durations: np.ndarrayExclusive duration of every call in seconds.
exclusive_durations_nsproperty#
exclusive_durations_ns: np.ndarrayExclusive duration of every call in nanoseconds.
first_durationproperty#
first_duration: floatDuration of the first recorded call, in seconds.
first_start_timeproperty#
first_start_time: floatFirst start time in seconds.
gpu_average_durationproperty#
gpu_average_duration: float | NoneAverage CUDA-event elapsed device time in seconds, or None if absent.
gpu_durationsproperty#
gpu_durations: np.ndarray | NoneCUDA-event elapsed device times in seconds, or None if absent.
gpu_durations_nsproperty#
gpu_durations_ns: np.ndarray | NoneCUDA-event elapsed device times in nanoseconds, or None if absent.
gpu_total_durationproperty#
gpu_total_duration: float | NoneTotal CUDA-event elapsed device time in seconds, or None if absent.
has_event_dataproperty#
has_event_data: boolWhether per-call timestamps were loaded for this region.
has_gpu_timingproperty#
has_gpu_timing: boolWhether this region has CUDA-event elapsed timings.
has_sourceproperty#
has_source: boolWhether this region’s call-site source was captured.
has_thread_dataproperty#
has_thread_data: boolWhether this region recorded the thread each call ran on.
has_timingproperty#
has_timing: boolWhether this region recorded any calls at all.
inclusive_durationproperty#
inclusive_duration: floatTotal inclusive time, including nested regions, in seconds.
inclusive_durationsproperty#
inclusive_durations: np.ndarrayInclusive duration of every call in seconds.
inclusive_durations_nsproperty#
inclusive_durations_ns: np.ndarrayInclusive duration of every call in nanoseconds.
last_durationproperty#
last_duration: floatDuration of the last recorded call, in seconds.
last_end_timeproperty#
last_end_time: floatLast end time in seconds.
max_durationproperty#
max_duration: floatMaximum duration among all calls in seconds.
min_durationproperty#
min_duration: floatMinimum duration among all calls in seconds.
num_callsproperty#
num_calls: intNumber of recorded calls.
p50_durationproperty#
p50_duration: float | NoneMedian duration in seconds.
p95_durationproperty#
p95_duration: float | None95th-percentile duration in seconds.
p99_durationproperty#
p99_duration: float | None99th-percentile duration in seconds.
parent_idsproperty#
parent_idsExplicit parent ids, or None for legacy profiles.
source_fileproperty#
source_file: str | NonePath of the file this region is defined in, or None if not captured.
source_linenoproperty#
source_lineno: int | NoneLine the region’s call site starts at, or None if not captured.
source_textproperty#
source_text: str | NoneSource text of the region’s with block or decorated function.
None if it was not captured - either the file it came from is no longer readable, or the file predates this being recorded.
start_timesproperty#
start_times: np.ndarrayStart times of all calls in seconds.
start_times_nsproperty#
start_times_ns: np.ndarrayStart times of all calls in nanoseconds, exactly as stored.
std_durationproperty#
std_duration: floatStandard deviation of durations in seconds.
stored_summaryproperty#
stored_summary: dict | NoneFixed-size statistics used by aggregate and summary-only results.
tagsproperty#
tags: tuple[str, ...]User-defined tags attached to this region.
task_idsproperty#
task_ids: np.ndarray | NoneTask-table index of every call, -1 outside a task.
None unless the run used track_async.
thread_idsproperty#
thread_ids: np.ndarray | NoneThread-table index of every call, or None if threads were not tracked.
threadsproperty#
threads: list[int]Sorted thread-table indices this region recorded calls on.
total_await_durationproperty#
total_await_duration: float | NoneTotal awaited seconds over every call, or None if not tracked.
total_durationproperty#
total_duration: floatTotal time spent in this region in seconds (sum of all durations).
total_exclusive_durationproperty#
total_exclusive_duration: floatTotal time excluding nested regions, in seconds.
eventsmethod#
def events(origin: float = 0.0) -> list[dict[str, Any]]Return one dict per recorded call.
Parameters
origin : float, optional
Seconds subtracted from every timestamp, so passing
results.minimum_start_time yields a timeline starting at zero
(default: 0.0, i.e. raw timestamps).
Returns
list of dict
One entry per call with keys call_index, start, end
and duration, in seconds and in recorded order.
for_threadmethod#
def for_thread(thread_index: int) -> RegionA view of this region holding only the calls of one thread.
Every column is sliced with the same mask, so the returned region is
an ordinary :class:Region - summaries, durations and percentiles
all describe that thread alone.
Raises
ValueError
If this region has no thread column (the run did not use
track_threads).
get_summarymethod#
def get_summary() -> dict[str, Any]Return a summary of the region’s statistics as a dictionary.
Returns
Dict[str, Any] Dictionary containing statistics: num_calls, total_duration, average_duration, min_duration, max_duration, first_duration, last_duration, and std_duration. Durations are in seconds.
percentile_durationmethod#
def percentile_duration(percentile: float) -> float | NoneReturn a duration percentile in seconds.
percentile follows :func:numpy.percentile and must be between
0 and 100. Empty regions return 0.0 for consistency with the
other duration statistics.