Release Notes¶
Changes in the HyperAccel Profiler (hapti). For changes across the whole stack, see the SDK release notes.
0.0.6 — 2026-11-16¶
Version: 0.0.6. Requires Python 3.10 or later and Runtime 0.0.6.
Migration (Breaking Changes)¶
| Item | Before | 0.0.6 |
|---|---|---|
| Counter selection environment variable | HA_PROFILE_COUNTERS | HAPTI_COUNTERS The old name is no longer read |
For configuration, see Environment Variables.
New Features¶
- Configurable device record ring size — HAPTI_DEVICE_RING_BYTES sets the size of the host ring that receives device records. The default is 1 MiB, and the number can take a K, M, or G suffix (1024-based). If a record loss warning appears, increase this value.
Fixes¶
- Fixed MPU segments not being shown on the signal logger track.
- Fixed the hapti shared libraries not being found in wheel installations.
0.0.5 — 2026-10-14¶
Version: 0.0.5. Requires Python 3.10 or later and Runtime 0.0.5.
New Features¶
- Output control options now take effect — -d, -o, -f, and --log-level are passed to the tool, so you can set the output directory, file name, and format. With --profile-children, the -o value becomes the prefix of the per-rank file names. See the CLI Reference.
- Memory transfer bandwidth — H2D and D2H transfer slices of 4 KiB or more carry a measured bandwidth, and haprof traces gain a per-device bandwidth counter track.
- Kineto plugin device timeline — The Kineto plugin collects the device kernel and memory transfer timeline, controlled by HAPTI_KINETO_DEVICE_TRACE and HAPTI_KINETO_DEVICE. See Device Timeline Collection in PyTorch Profiler Integration.
- Device record loss warnings — When records are lost, a warning is printed at process exit. It distinguishes three cases. - Records overwritten because the reader fell behind the ring - Records the driver dropped before writing them to the ring - Signal logger executions that could not be shown because their kernel record was missing
Changes¶
- Per-execution signal logger collection — The tool creates a slot pool in user space and registers it with the runtime, and the runtime reads and hands over the data for each execution.
- Environment variable isolation — The launcher sets all HAPTI_* environment variables anew on every run, so values left in the shell do not leak into the tool's configuration.
- Device record ring drain order — At runtime shutdown or device reset, the device record ring is drained and released before the device's resources are reclaimed.
Fixes¶
- Fixed a bug where signal logger data for an execution with no kernel record was drawn over another kernel. That execution is now not shown, and a warning is printed.
- Fixed meaningless bandwidth values shown for D2D transfers and small transfers.
0.0.4 — 2026-07-15¶
Version: 0.0.4rc4. Requires Python 3.10 – 3.12 and Runtime 0.0.4.
Highlights¶
- Two-level device tracing — --runtime-trace collects the device kernel and transfer timeline, and --device-trace adds per-kernel hardware counters and the signal logger on top of it.
- 6 hardware blocks, 41 counter events — Includes stall breakdown metrics that distinguish memory-bound from compute-bound.
- PyTorch profiler integration — Through a Kineto plugin.
New Features¶
| Area | Added |
|---|---|
| Device tracing options | --runtime-trace, --device-trace (passed to the tool through HAPTI_TOOL_DEVICE_TIMELINE and HAPTI_TOOL_DEVICE_COUNTERS) |
| Hardware counters | Per-kernel-execution counter collection. Events selected with HA_PROFILE_COUNTERS |
| Multi-rank | --profile-children for fork-based multi-rank runs haprof merge, which merges per-rank traces into a straggler report |
| User annotation API | annotate, range_push / range_pop, range_start / range_stop, mark |
| Device selection | HAPTI_TOOL_DEVICE_ID (the device whose records are collected) |
Changes¶
- Unified counter representation — haprof and the Kineto plugin show the same counters the same way (per-execution delta, utilization, bandwidth).
- Timeline linking — Host and device timelines are linked by correlation id instead of being compared side by side.
Known Issues¶
| Issue | Impact | Workaround |
|---|---|---|
| Most CLI options are parsed but not applied | -o, -d, -f, --log-level, and per-domain trace flags are ignored | Change to the target directory before running |
| The profiler's own overhead is not recorded | The overhead activity kind is empty | Compare with a run without the profiler |
| Memory allocation records have no device information | Allocation locations cannot be told apart on multi-device systems | — |
| Limited default counter scope | Only the 20 events of core 0 (AXIBRG, DMC, UTIL) are collected; CDMA, CGDMA, MPU, and other cores are not | Specify them with HA_PROFILE_COUNTERS |
| One device per trace | In a multi-device process, kernels of only one device are recorded | Set HAPTI_TOOL_DEVICE_ID, or split ranks per device and use --profile-children |
| No device timeline or hapti annotations on the Kineto path | torch.profiler traces show only runtime API calls and the layers below | Use the haprof launcher |
| Configuration is fixed at process start | A running process cannot be profiled, and profiling cannot be started or stopped mid-run | Mark the range to analyze with annotations |
| Traces are written at process exit | A forcibly killed process leaves no result file | Exit normally with an interrupt signal instead of SIGKILL |
| The first execution is not a measurement target | It includes kernel binary loading and has no baseline for counter deltas | Analyze executions after enough warm-up |
| CGDMA bandwidth is not measured | It is a utilization metric scaled by firmware constants | Use it only for relative comparison between executions, not as an absolute rate |
| Utilization is aggregated by sampling | Units that run in short bursts may be under-counted | Check it together with the stall breakdown metrics |
Version Support¶
| Version | Release date | Status |
|---|---|---|
| 0.0.6 | 2026-11-16 | Current |
| 0.0.5 | 2026-10-14 | Superseded |
| 0.0.4 | 2026-07-15 | Superseded |
hapti is in beta.
- The trace output formats (Perfetto Protobuf, Chrome JSON) follow external standards and are stable.
- The CLI is still being wired up, so option behavior may change between releases. In particular, the per-domain trace flags are currently parsed and ignored; do not assume they will stay ignored.
- Entry points scheduled for deprecation (APIs, options) are announced in the release in which the deprecation is decided, and they remain for at least two subsequent releases before removal.