tensorplay@1.0.0.dev20260909

A list of profiling events with helper methods for analysis and visualization.

EventList extends the standard Python list to provide specialized methods for working with profiling events (FunctionEvent or FunctionEventAvg objects). It includes utilities for aggregating statistics, formatting output tables, and exporting profiling data.

This class is typically returned by profiler methods and should not be instantiated directly by users.

Parameters:

• *args – Standard list arguments.

• use_device (str, optional) – Device type for profiling (“cuda”, “xpu”, etc.).

• profile_memory (bool, optional) – Whether memory profiling was enabled. Default: False.

• with_flops (bool, optional) – Whether to include FLOP counts. Default: False.

Variables:

• _use_device (str) – Device type being profiled.

• _profile_memory (bool) – Whether memory profiling is enabled.

• _with_flops (bool) – Whether FLOP counting is enabled.

• _tree_built (bool) – Whether the event tree structure has been built.

Key Methods:

table(…): Format events as a table string for display. export_chrome_trace(path): Export to Chrome tracing format. export_stacks(path, metric): Export stack traces with metrics. key_averages(…): Compute averaged statistics grouped by operation name. total_average(): Compute aggregate totals across all events (sums, not averages).

Properties:

self_cpu_time_total: Sum of self CPU time across all events.

Example:

import tensorplay
from tensorplay.profiler import profile, ProfilerActivity

with profile(activities=[ProfilerActivity.CPU]) as prof:
    x = tensorplay.randn(100, 100)
    y = tensorplay.matmul(x, x)

# EventList is returned by prof.events()
events = prof.events()

# Display as formatted table
print(
    events.table(
        sort_by="cpu_time_total", row_limit=20, top_level_events_only=False
    )
)

# Export to Chrome tracing format
events.export_chrome_trace("trace.json")

# Get averaged statistics
avg_events = events.key_averages()
print(avg_events.table())

# Export stack traces
events.export_stacks("stacks.txt", "self_cpu_time_total")

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

export_chrome_trace(path, **_kwargs)[source]

Export an EventList as a Chrome tracing tools file.

The checkpoint can be later loaded and inspected under chrome://tracing URL.

Parameters:

path (str) – Path where the trace will be written.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

key_averages(group_by_input_shapes=False, group_by_input_shape=None, group_by_stack_n=0, group_by_overload_name=False, include_python_functions=False)[source]

Averages all function events over their keys.

Parameters:

• group_by_input_shapes – group entries by (event name, input shapes) rather than just event name. This is useful to see which input shapes contribute to the runtime the most and may help with size-specific optimizations or choosing the best candidates for quantization (aka fitting a roof line)

• group_by_stack_n – group by top n stack trace entries

• group_by_overload_name – Differentiate operators by their overload name e.g. tensorplay::add.Tensor

• separately (and tensorplay::add.out will be aggregated)

• include_python_functions – include Python function events (e.g. individual Python callsite entries captured with with_stack=True) in the averages. By default these are excluded because they tend to appear as misleading hotspots (e.g. threading.py: wait) that obscure the real operator-level breakdown. Set to True to restore the raw per-callsite view.

Returns:

An EventList containing FunctionEventAvg objects.

pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

table(sort_by=None, row_limit=100, max_src_column_width=75, max_name_column_width=55, max_shapes_column_width=80, header=None, top_level_events_only=False, time_unit=None)[source]

Print an EventList as a nicely formatted table.

Parameters:

• sort_by (str, optional) – Attribute used to sort entries. By default they are printed in the same order as they were registered. Valid keys include: cpu_time, cuda_time, xpu_time, cpu_time_total, cuda_time_total, xpu_time_total, cpu_memory_usage, cuda_memory_usage, xpu_memory_usage, self_cpu_memory_usage, self_cuda_memory_usage, self_xpu_memory_usage, count.

• top_level_events_only (bool, optional) – Boolean flag to determine the selection of events to display. If true, the profiler will only display events at top level like top-level invocation of python lstm, python add or other functions, nested events like low-level cpu/cuda/xpu ops events are omitted for profiler result readability.

• time_unit (str, optional) – A time unit to be used for all values in the table. Valid options are: s, ms and us.

Returns:

A string containing the table.

total_average()[source]

Compute aggregate statistics across all events.

Accumulates statistics from all events into a single FunctionEventAvg object. This is primarily useful for computing total metrics (total CPU time, total memory usage, etc.) across the entire profiling session, regardless of operation type.

Note

This sums up times and counts across ALL different operations, so the “average” metrics (like cpu_time) represent the average time per operation call across the entire session, mixing all operation types together. For per-operation averages, use key_averages() instead.

Returns:

A single aggregate object with key=”Total” containing

accumulated statistics.

Return type:

FunctionEventAvg

Helpers for FunctionEvent and FunctionEventAvg.

The subclass should define *_time_total and count attributes.

Profiling information about a single function.

FunctionEvent records the execution of a single operation during profiling. These events are obtained from the profiler/kineto and contain detailed timing and memory usage information.

Variables:

• id (int) – Unique identifier for this event.

• node_id (int) – Node identifier for distributed profiling (-1 if not applicable).

• name (str) – Name of the profiled function/operator.

• overload_name (str) – Overload name for the operator (requires _ExperimentalConfig(capture_overload_names=True) set).

• trace_name (str) – Same as name, just changes ProfilerStep* to ProfilerStep#

• time_range (Interval) – Time interval containing start and end timestamps in microseconds.

• thread (int) – Thread ID where the operation started.

• fwd_thread (int) – Thread ID of the corresponding forward operation.

• kernels (List[Kernel]) – List of device kernels launched by this operation.

• count (int) – Number of times this event was called (usually 1).

• cpu_children (List[FunctionEvent]) – Direct CPU child operations.

• cpu_parent (FunctionEvent) – Direct CPU parent operation.

• input_shapes (List[List[int]]) – Shapes of input tensors (requires record_shapes=True). For plain tensor inputs, each entry is a list of dimensions (e.g. [16, 16]). TensorList inputs are represented as an empty list []; use structured_input_shapes to get per-element shapes for TensorList inputs.

• concrete_inputs (List[Any]) – Concrete input values (requires record_shapes=true).

• kwinputs (Dict[str, Any]) – Keyword arguments (requires record_shapes=true).

• stack (List[str]) – Python stack trace where the operation was called (requires with_stack=true).

• scope (int) – record-scope identifier (0=forward, 1=backward, etc.).

• use_device (str) – Device type being profiled (“cuda”, “xpu”, etc.).

• cpu_memory_usage (int) – CPU memory allocated in bytes.

• device_memory_usage (int) – Device memory allocated in bytes.

• is_async (bool) – Whether this is an asynchronous operation.

• is_remote (bool) – Whether this operation occurred on a remote node.

• sequence_nr (int) – Sequence number for autograd operations.

• device_type (DeviceType) – Type of device (CPU, CUDA, XPU, PrivateUse1, etc.).

• device_index (int) – Index of the device (e.g., GPU 0, 1, 2).

• device_resource_id (int) – Resource ID on the device (ie. stream ID).

• is_legacy (bool) – Whether this is from the legacy profiler.

• flops (int) – Estimated floating point operations.

• is_user_annotation (bool) – Whether this is a user-annotated region.

• metadata (Dict[str, Any]) – Additional metadata keyed by the field names used in exported traces. Use _ExperimentalConfig(expose_kineto_event_metadata=True) to expose Kineto activity metadata. Available fields vary by activity and backend.

• metadata_json (str) – Deprecated. Use event_metadata instead.

• event_metadata (EventMetadata) – Additional metadata in structured format.

• structured_input_shapes (List[List[int] | List[List[int]]]) – Like input_shapes but distinguishes TensorList inputs. Plain tensor inputs are List[int]; TensorList inputs are List[List[int]] containing one shape per tensor in the list. Matches the "Input Dims" field in the Chrome trace JSON.

• structured_input_strides (List[List[int] | List[List[int]]]) – Strides of input tensors in the same format as structured_input_shapes (requires record_shapes=True).

Properties:

cpu_time_total (float): Total CPU time in microseconds. device_time_total (float): Total device (CUDA/XPU/etc) time in microseconds. self_cpu_time_total (float): CPU time excluding child operations. self_device_time_total (float): Device time excluding child operations. self_cpu_memory_usage (int): CPU memory usage excluding child operations. self_device_memory_usage (int): Device memory usage excluding child operations. cpu_time (float): Average CPU time per call. device_time (float): Average device time per call. key (str): Key used for grouping events (usually same as name).

append_cpu_child(child)[source]

Append a CPU child of type FunctionEvent.

One is supposed to append only direct children to the event to have correct self cpu time being reported.

set_cpu_parent(parent)[source]

Set the immediate CPU parent of type FunctionEvent.

One profiling FunctionEvent should have only one CPU parent such that the child’s range interval is completely inside the parent’s. We use this connection to determine the event is from top-level op or not.

Averaged profiling statistics over multiple FunctionEvent objects.

FunctionEventAvg aggregates statistics from multiple FunctionEvent objects with the same key (typically same operation name). This is useful for getting average performance metrics across multiple invocations of the same operation.

This class is typically created by calling EventList.key_averages() on a profiler’s event list.

Variables:

• key (str) – Grouping key for the events (typically operation name).

• count (int) – Total number of events aggregated.

• node_id (int) – Node identifier for distributed profiling (-1 if not applicable).

• is_async (bool) – Whether the operations are asynchronous.

• is_remote (bool) – Whether the operations occurred on a remote node.

• use_device (str) – Device type being profiled (“cuda”, “xpu”, etc.).

• cpu_time_total (int) – Accumulated total CPU time in microseconds.

• device_time_total (int) – Accumulated total device time in microseconds.

• self_cpu_time_total (int) – Accumulated self CPU time (excluding children) in microseconds.

• self_device_time_total (int) – Accumulated self device time (excluding children) in microseconds.

• input_shapes (List[List[int]]) – Input tensor shapes (requires record_shapes=true).

• overload_name (str) – Operator overload name (requires _ExperimentalConfig(capture_overload_names=True) set).

• stack (List[str]) – Python stack trace where the operation was called (requires with_stack=true).

• scope (int) – record-scope identifier (0=forward, 1=backward, etc.).

• cpu_memory_usage (int) – Accumulated CPU memory usage in bytes.

• device_memory_usage (int) – Accumulated device memory usage in bytes.

• self_cpu_memory_usage (int) – Accumulated self CPU memory usage in bytes.

• self_device_memory_usage (int) – Accumulated self device memory usage in bytes.

• cpu_children (List[FunctionEvent]) – CPU child events.

• cpu_parent (FunctionEvent) – CPU parent event.

• device_type (DeviceType) – Type of device (CPU, CUDA, XPU, PrivateUse1, etc.).

• is_legacy (bool) – Whether from legacy profiler.

• flops (int) – Total floating point operations.

• is_user_annotation (bool) – Whether this is a user-annotated region.

Properties:

cpu_time (float): Average CPU time per invocation. device_time (float): Average device time per invocation.

elapsed_us()[source]

Returns the length of the interval

count(value, /)

Return number of occurrences of value.

device

Alias for field number 1

duration

Alias for field number 2

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

name

Alias for field number 0

Acceleration structure for accessing mem_records in interval.

in_interval(start_ns, end_ns)[source]

Return all records in the given interval

clear() → None.  Remove all items from D.

copy() → a shallow copy of D.

default_factory

Factory for default value called by __missing__().

classmethod fromkeys(iterable, value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values