Skip to content

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