API Reference
hapti provides two interfaces. In a typical user environment the CLI is enough; the Python API is provided for code
range annotations and PyTorch integration.
| Interface |
Role and audience |
Main entry points |
| CLI |
The primary tool that runs a program under the profiler and merges traces (for most users) |
haprof, haprof merge |
| Python API |
Annotations in code and PyTorch profiler integration |
annotate, mark, hapti.kineto.register, and others |
Semantics such as when records are collected, how device time appears, and how to read counters are the same for
both interfaces and are described once in the Programming Guide. This section
covers options and signatures.
Entry Points by Area
| Area |
Entry points |
Reference |
| Running and merging |
haprof, haprof merge |
CLI |
| Annotations |
annotate, range_push, range_pop, range_start, range_stop, mark |
Python API |
| PyTorch integration |
hapti.kineto.register |
Python API |
Reference Pages
| Page |
Use it when |
| Counter Reference |
You need the meaning of the 41 hardware counters and of the derived metrics shown in the trace (util% and so on) |
| Environment Variables |
You configure with environment variables instead of CLI options, or select counters to collect with HAPTI_COUNTERS |
| Support Matrix |
You need the supported platforms and what can and cannot be collected |
Common Semantics
| Property |
Value |
| Integration |
LD_PRELOAD set by the launcher. No source changes and no rebuild |
| Scope |
Per process. Fixed at process start |
| Output |
Perfetto .pftrace and Chrome .json. Both by default |
| Output location |
The directory where haprof was run, or -d |
| Write time |
At process exit |
| Device records |
Emitted at the device's batch boundaries, not at call time |
| Clock |
All timestamps are host CLOCK_MONOTONIC nanoseconds |
| Counters |
20 of 41 registered by default. Sampled per kernel execution and shown as deltas or percentages |
| Devices per trace |
One |
| Python API |
For annotations and PyTorch integration only. Does not start, stop, or configure profiling |
See Also