# tensorplay.autograd.profiler_util API

Source: https://www.tensorplay.cn/docs/api/tensorplay.autograd.profiler_util.html

## Classes 8

[#](#api-tensorplay.autograd.profiler_util.EventList)

### EventList

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.EventList.html)

```python
class tensorplay.autograd.profiler_util.EventList(*args, **kwargs)
```

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](https://docs.python.org/3/builtins/stdtypes.html#str), optional) – Device type for profiling (“cuda”, “xpu”, etc.).

- profile_memory ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether memory profiling was enabled. Default: False.

- with_flops ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether to include FLOP counts. Default: False.

Variables:

- _use_device ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Device type being profiled.

- _profile_memory ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether memory profiling is enabled.

- _with_flops ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether FLOP counting is enabled.

- _tree_built ([bool](https://docs.python.org/3/builtins/functions.html#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")
```

> **See also**
>
> FunctionEvent: Individual profiling event FunctionEventAvg: Averaged profiling statistics table(): Format events as a readable table key_averages(): Aggregate events by operation name

```python
clear()
```

Remove all items from list.

```python
copy()
```

Return a shallow copy of the list.

```python
count(value, /)
```

Return number of occurrences of value.

```python
export_chrome_trace(path, **_kwargs)
```

Export an EventList as a Chrome tracing tools file.

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

Parameters:

path ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path where the trace will be written.

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

Return first index of value.

Raises ValueError if the value is not present.

```python
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)
```

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.

```python
pop(index=-1, /)
```

Remove and return item at index (default last).

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

```python
remove(value, /)
```

Remove first occurrence of value.

Raises ValueError if the value is not present.

```python
reverse()
```

Reverse IN PLACE.

```python
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.

```python
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)
```

Print an EventList as a nicely formatted table.

Parameters:

- sort_by ([str](https://docs.python.org/3/builtins/stdtypes.html#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](https://docs.python.org/3/builtins/functions.html#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](https://docs.python.org/3/builtins/stdtypes.html#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.

```python
total_average()
```

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](/docs/generated/tensorplay.autograd.profiler_util.FunctionEventAvg.html#tensorplay.autograd.profiler_util.FunctionEventAvg)

[#](#api-tensorplay.autograd.profiler_util.FormattedTimesMixin)

### FormattedTimesMixin

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.FormattedTimesMixin.html)

```python
class tensorplay.autograd.profiler_util.FormattedTimesMixin
```

Helpers for FunctionEvent and FunctionEventAvg.

The subclass should define *_time_total and count attributes.

[#](#api-tensorplay.autograd.profiler_util.FunctionEvent)

### FunctionEvent

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.FunctionEvent.html)

```python
class tensorplay.autograd.profiler_util.FunctionEvent(id, name, thread, start_us, end_us, overload_name=None, fwd_thread=None, input_shapes=None, stack=None, scope=0, use_device=None, cpu_memory_usage=0, device_memory_usage=0, is_async=False, is_remote=False, sequence_nr=-1, node_id=-1, device_type=<DeviceType.CPU: 0>, device_index=0, device_resource_id=None, is_legacy=False, flops=None, trace_name=None, concrete_inputs=None, kwinputs=None, is_user_annotation=False, is_python_function=False, activity_type=None, metadata_json=None, flow_id=None, flow_type=None, flow_start=None, external_id=0, linked_correlation_id=0, extra_meta=None, structured_input_shapes=None, structured_input_strides=None, input_dtypes=None, python_id=-1, python_parent_id=-1, python_module_id=-1, typed_metadata=None)
```

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.

> **Note**
>
> FunctionEvent objects are typically created by the profiler/kineto and should not be instantiated directly by users. Access them through the profiler’s output.

Variables:

- id ([int](https://docs.python.org/3/builtins/functions.html#int)) – Unique identifier for this event.

- node_id ([int](https://docs.python.org/3/builtins/functions.html#int)) – Node identifier for distributed profiling (-1 if not applicable).

- name ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the profiled function/operator.

- overload_name ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Overload name for the operator (requires _ExperimentalConfig(capture_overload_names=True) set).

- trace_name ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Same as name, just changes ProfilerStep* to ProfilerStep#

- time_range ([Interval](/docs/generated/tensorplay.autograd.profiler_util.Interval.html#tensorplay.autograd.profiler_util.Interval)) – Time interval containing start and end timestamps in microseconds.

- thread ([int](https://docs.python.org/3/builtins/functions.html#int)) – Thread ID where the operation started.

- fwd_thread ([int](https://docs.python.org/3/builtins/functions.html#int)) – Thread ID of the corresponding forward operation.

- kernels (List[[Kernel](/docs/generated/tensorplay.autograd.profiler_util.Kernel.html#tensorplay.autograd.profiler_util.Kernel)]) – List of device kernels launched by this operation.

- count ([int](https://docs.python.org/3/builtins/functions.html#int)) – Number of times this event was called (usually 1).

- cpu_children (List[[FunctionEvent](#tensorplay.autograd.profiler_util.FunctionEvent)]) – Direct CPU child operations.

- cpu_parent ([FunctionEvent](#tensorplay.autograd.profiler_util.FunctionEvent)) – Direct CPU parent operation.

- input_shapes (List[List[[int](https://docs.python.org/3/builtins/functions.html#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](https://docs.python.org/3/builtins/stdtypes.html#str), Any]) – Keyword arguments (requires record_shapes=true).

- stack (List[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]) – Python stack trace where the operation was called (requires with_stack=true).

- scope ([int](https://docs.python.org/3/builtins/functions.html#int)) – record-scope identifier (0=forward, 1=backward, etc.).

- use_device ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Device type being profiled (“cuda”, “xpu”, etc.).

- cpu_memory_usage ([int](https://docs.python.org/3/builtins/functions.html#int)) – CPU memory allocated in bytes.

- device_memory_usage ([int](https://docs.python.org/3/builtins/functions.html#int)) – Device memory allocated in bytes.

- is_async ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether this is an asynchronous operation.

- is_remote ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether this operation occurred on a remote node.

- sequence_nr ([int](https://docs.python.org/3/builtins/functions.html#int)) – Sequence number for autograd operations.

- device_type ([DeviceType](/docs/generated/tensorplay.DeviceType.html#tensorplay.DeviceType)) – Type of device (CPU, CUDA, XPU, PrivateUse1, etc.).

- device_index ([int](https://docs.python.org/3/builtins/functions.html#int)) – Index of the device (e.g., GPU 0, 1, 2).

- device_resource_id ([int](https://docs.python.org/3/builtins/functions.html#int)) – Resource ID on the device (ie. stream ID).

- is_legacy ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether this is from the legacy profiler.

- flops ([int](https://docs.python.org/3/builtins/functions.html#int)) – Estimated floating point operations.

- is_user_annotation ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether this is a user-annotated region.

- metadata (Dict[[str](https://docs.python.org/3/builtins/stdtypes.html#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](https://docs.python.org/3/builtins/stdtypes.html#str)) – Deprecated. Use event_metadata instead.

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

- structured_input_shapes (List[List[[int](https://docs.python.org/3/builtins/functions.html#int)] | List[List[[int](https://docs.python.org/3/builtins/functions.html#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](https://docs.python.org/3/builtins/functions.html#int)] | List[List[[int](https://docs.python.org/3/builtins/functions.html#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).

> **See also**
>
> tensorplay.profiler.profile: Context manager for profiling EventList: List container for FunctionEvent objects with helper methods FunctionEventAvg: Averaged statistics over multiple FunctionEvent objects

```python
append_cpu_child(child)
```

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.

```python
set_cpu_parent(parent)
```

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.

[#](#api-tensorplay.autograd.profiler_util.FunctionEventAvg)

### FunctionEventAvg

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.FunctionEventAvg.html)

```python
class tensorplay.autograd.profiler_util.FunctionEventAvg
```

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()](/docs/generated/tensorplay.autograd.profiler_util.EventList.html#tensorplay.autograd.profiler_util.EventList.key_averages) on
a profiler’s event list.

Variables:

- key ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Grouping key for the events (typically operation name).

- count ([int](https://docs.python.org/3/builtins/functions.html#int)) – Total number of events aggregated.

- node_id ([int](https://docs.python.org/3/builtins/functions.html#int)) – Node identifier for distributed profiling (-1 if not applicable).

- is_async ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether the operations are asynchronous.

- is_remote ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether the operations occurred on a remote node.

- use_device ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Device type being profiled (“cuda”, “xpu”, etc.).

- cpu_time_total ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated total CPU time in microseconds.

- device_time_total ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated total device time in microseconds.

- self_cpu_time_total ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated self CPU time (excluding children) in microseconds.

- self_device_time_total ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated self device time (excluding children) in microseconds.

- input_shapes (List[List[[int](https://docs.python.org/3/builtins/functions.html#int)]]) – Input tensor shapes (requires record_shapes=true).

- overload_name ([str](https://docs.python.org/3/builtins/stdtypes.html#str)) – Operator overload name (requires _ExperimentalConfig(capture_overload_names=True) set).

- stack (List[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]) – Python stack trace where the operation was called (requires with_stack=true).

- scope ([int](https://docs.python.org/3/builtins/functions.html#int)) – record-scope identifier (0=forward, 1=backward, etc.).

- cpu_memory_usage ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated CPU memory usage in bytes.

- device_memory_usage ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated device memory usage in bytes.

- self_cpu_memory_usage ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated self CPU memory usage in bytes.

- self_device_memory_usage ([int](https://docs.python.org/3/builtins/functions.html#int)) – Accumulated self device memory usage in bytes.

- cpu_children (List[[FunctionEvent](/docs/generated/tensorplay.autograd.profiler_util.FunctionEvent.html#tensorplay.autograd.profiler_util.FunctionEvent)]) – CPU child events.

- cpu_parent ([FunctionEvent](/docs/generated/tensorplay.autograd.profiler_util.FunctionEvent.html#tensorplay.autograd.profiler_util.FunctionEvent)) – CPU parent event.

- device_type ([DeviceType](/docs/generated/tensorplay.DeviceType.html#tensorplay.DeviceType)) – Type of device (CPU, CUDA, XPU, PrivateUse1, etc.).

- is_legacy ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether from legacy profiler.

- flops ([int](https://docs.python.org/3/builtins/functions.html#int)) – Total floating point operations.

- is_user_annotation ([bool](https://docs.python.org/3/builtins/functions.html#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.

> **See also**
>
> EventList.key_averages: Method that creates FunctionEventAvg objects FunctionEvent: Individual profiling event EventList: Container for profiling events

[#](#api-tensorplay.autograd.profiler_util.Interval)

### Interval

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.Interval.html)

```python
class tensorplay.autograd.profiler_util.Interval(start, end)
```

```python
elapsed_us()
```

Returns the length of the interval

[#](#api-tensorplay.autograd.profiler_util.Kernel)

### Kernel

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.Kernel.html)

```python
class tensorplay.autograd.profiler_util.Kernel(name, device, duration)
```

```python
count(value, /)
```

Return number of occurrences of value.

```python
device
```

Alias for field number 1

```python
duration
```

Alias for field number 2

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

Return first index of value.

Raises ValueError if the value is not present.

```python
name
```

Alias for field number 0

[#](#api-tensorplay.autograd.profiler_util.MemRecordsAcc)

### MemRecordsAcc

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.MemRecordsAcc.html)

```python
class tensorplay.autograd.profiler_util.MemRecordsAcc(mem_records)
```

Acceleration structure for accessing mem_records in interval.

```python
in_interval(start_ns, end_ns)
```

Return all records in the given interval

[#](#api-tensorplay.autograd.profiler_util.StringTable)

### StringTable

class[Full reference ↗](/docs/generated/tensorplay.autograd.profiler_util.StringTable.html)

```python
class tensorplay.autograd.profiler_util.StringTable
```

```python
clear() &#x2192; None.&#160; Remove all items from D.
```

```python
copy() &#x2192; a shallow copy of D.
```

```python
default_factory
```

Factory for default value called by __missing__().

```python
classmethod fromkeys(iterable, value=None, /)
```

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

```python
get(key, default=None, /)
```

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

```python
items() &#x2192; a set-like object providing a view on D's items
```

```python
keys() &#x2192; a set-like object providing a view on D's keys
```

```python
pop(k[, d]) &#x2192; v, remove specified key and return the corresponding value.
```

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

```python
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.

```python
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.

```python
update([E, ]**F) &#x2192; None.&#160; Update D from mapping/iterable E and F.
```

If E is present and has a .keys() method, then does:  for k in E.keys(): 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]

```python
values() &#x2192; an object providing a view on D's values
```