HyperAccel Profiler (hapti)¶
HyperAccel Profiler(hapti)는 애플리케이션과 LPU의 실행 흐름을 하나의 타임라인으로 기록하고, Perfetto와 Chrome 뷰어에서 열 수 있는 형식으로 저장합니다. hapti는 HyperAccel Profiling and Tracing Interface의 약자이며, 기존 애플리케이션 코드를 수정하거나 다시 빌드하지 않고도 프로파일링할 수 있습니다.
주요 장점¶
- 코드 수정 없이 프로파일링 — 실행 명령 앞에
haprof를 붙이기만 하면 됩니다(예:haprof -- python infer.py). 소스 코드 수정, 재빌드, 모듈 import, 초기화 함수 호출이 필요 없습니다. - 옵션으로 수집 범위 선택 — 디바이스 타임라인, 하드웨어 카운터 같은 수집 범위와 출력 위치·형식을 실행 옵션으로 정합니다.
- 멀티 랭크 트레이스 병합 — 랭크마다 따로 생성된 트레이스를
haprof merge로 하나의 타임라인으로 합칩니다. - PyTorch 연동 — 코드 한 줄로 디바이스 활동을
torch.profiler트레이스에 함께 기록할 수 있습니다.
이렇게 설계한 배경은 프로그래밍 가이드의 설계 배경을 참고하십시오.
아키텍처 개요¶
hapti는 애플리케이션 실행에 직접 관여하지 않는 관찰 도구입니다. 커널 실행, 메모리 및
스트림 관리는 기존과 동일하게 런타임(hart)과 LPU가 담당하며, hapti는 그 실행 기록을 수집해
트레이스 파일로 남깁니다. 프로그램의 동작 및 결과는 변경되지 않으며, 프로파일링 오버헤드에 따른
실행 시간 차이만 발생합니다.
| 역할 | 담당 컴포넌트 |
|---|---|
| 커널 실행, 메모리, 스트림·이벤트 관리 | 런타임(hart) |
| 실행 기록 및 트레이스 파일 생성 | hapti |
| 트레이스 시각화 및 탐색 | Perfetto UI, Chrome tracing, torch.profiler |
아래 다이어그램과 같이 hapti는 실행 계층(hart, KMD, LPU)을 관찰하며, 다음 세 부분으로
구성됩니다.
- 진입점: 코드 수정 없이 실행하는
haprofCLI,torch.profiler에 통합하는 Kineto 플러그인, 코드 구간을 표시하는 Python 주석 - 수집 범위: 호스트 API 활동(런타임 API와 하위 계층 호출), 디바이스 활동(커널·메모리 전송), 하드웨어 카운터와 시그널 로거
- 타임라인 통합: 수집한 호스트 활동과 디바이스 활동을 하나의 타임라인으로 통합
각 기능의 요약은 hapti의 핵심 특징을 참고하십시오.
소프트웨어 스택에서의 hapti 위치와 기능
hapti의 핵심 특징¶
본 절에서는 hapti가 제공하는 핵심 기능과 동작 원칙을 요약하여 정리합니다. 각 항목에 대한 상세한
설명과 실무적 활용 방법은 프로그래밍 가이드 및
API 레퍼런스를 참고하시기 바랍니다.
| 특징 | 요약 |
|---|---|
| Zero-Code Profiling | haprof -- APP 한 줄로 기존 프로그램을 그대로 프로파일링합니다. 소스 코드 수정이나 재빌드가 필요 없으며, PyTorch 외의 일반 프로그램에도 적용됩니다. |
| Host API Tracing | 애플리케이션이 호출한 런타임 API와 런타임 내부의 하위 계층 호출 구간을 프로세스·스레드별 레인에 기록합니다. |
| Device Activity Tracing | LPU에서 실행된 커널과 메모리 전송을 디바이스·스트림별 타임라인에 기록합니다. --runtime-trace 옵션으로 활성화합니다(--device-trace에도 포함됩니다). |
| Per-Kernel Hardware Counters | 커널 실행마다 6개 블록, 41개 하드웨어 이벤트 중 선택한 카운터를 샘플링하여 메모리 바운드와 컴퓨트 바운드를 판별할 수 있게 합니다. |
| Signal Logger | 커널 실행 중 디바이스 내부 주요 유닛의 On/Off 신호 상태를 기록하여 커널 구간에 맞춰 트랙으로 표시합니다. |
| Host-Device Correlation | correlation id로 호스트 API 호출과 그 호출이 유발한 디바이스 활동을 연결합니다. |
| Single Clock Domain | 호스트와 디바이스 레코드를 모두 호스트 CLOCK_MONOTONIC 나노초 기준으로 변환하여, 같은 장비의 트레이스를 별도 보정 없이 하나의 타임라인에 정렬합니다. |
| User Annotations | Python 코드에서 구간(Range)과 시점(Mark)을 지정하여 애플리케이션 단계를 타임라인에 표시합니다. |
| PyTorch Profiler Integration | Kineto 플러그인으로 디바이스 활동을 torch.profiler 트레이스에 통합하고, CPU 연산과 디바이스 활동을 흐름 화살표로 연결합니다. |
| Multi-Process Capture & Merge | --profile-children으로 랭크별 트레이스를 수집하고, haprof merge로 하나의 타임라인과 Straggler 리포트로 병합합니다. |
| Standard Trace Formats | Perfetto(.pftrace)와 Chrome JSON(.json) 형식으로 저장하여 Perfetto UI나 Chrome tracing에서 바로 열 수 있습니다. |
| Low-Overhead Recording | 레코드 변환을 별도 워커 스레드에서 처리하여 애플리케이션 실행에 주는 지연을 줄입니다. 디바이스 수집 비용은 필요한 모드에서만 발생합니다. |
한눈에 보기¶
| 패키지 | hapti |
| 버전 | 0.0.6 |
| 언어 | C++20 코어, Python 바인딩(pybind11) |
| 산출물 | haprof CLI, libhapti_tool.so(preload 도구), libhapti_kineto_plugin.so(Kineto 플러그인), libha_hapti.so(코어), hapti Python 모듈 |
| 출력 포맷 | Perfetto(.pftrace), Chrome JSON(.json) |
| 연동 방식 | LD_PRELOAD (소스 코드 수정 및 재빌드 불필요) |
| PyTorch 연동 | Kineto 플러그인 |
| 하드웨어 카운터 | 6개 블록, 41개 이벤트 |
| Python | 3.10 – 3.12 |
| 상태 | Beta |
API 개요¶
일반적인 사용자 환경에서는 haprof CLI만으로 필요한 기능을 대부분 수행할 수 있습니다. Python API는 특정 코드 구간에 이름을 지정하는 주석(Annotation) 및 PyTorch 연동을 위해 제공됩니다.
| 구분 | 역할 | 주요 진입점 |
|---|---|---|
| CLI | 프로파일러 환경에서 프로그램을 실행하고 트레이스 병합 | haprof · haprof merge |
| Python API | 주석 지정 및 PyTorch 프로파일러 연동 | annotate · mark 외 4개, hapti.kineto.register |
첫 트레이스 수집¶
1 | |
실행 시 작업 디렉토리에 <hostname>_<pid>_<starttime>.pftrace 및 .json 파일이 생성됩니다.
생성된 .pftrace 파일은 ui.perfetto.dev에서 열람할 수 있습니다.
디바이스 실행 기록과 커널별 하드웨어 카운터까지 함께 수집하려면 아래 옵션을 추가하십시오.
1 | |
분석 시 주의사항¶
- 도메인별 트레이스 플래그는 아직 동작하지 않습니다.
--kernel-trace,--driver-trace등은 입력은 받지만 무시되며, 호스트 측 활동 데이터는 항상 전체 수집됩니다. 옵션별 지원 현황은 CLI 레퍼런스에 있습니다. - 디바이스 시간은 호출 시점이 아니라 배치 경계에서 드러납니다. 비동기 실행은 작업을 큐에 등록한 즉시 반환하고, 디바이스 레코드는 배치 처리가 끝난 뒤 생성됩니다. 호스트 호출과 디바이스 슬라이스의 가로 위치만으로 인과관계를 추론하지 마십시오. 디바이스 트레이싱: 디바이스 레코드가 수집되는 시점을 참고하십시오.
- 기본 하드웨어 카운터는 core 0의 20개 이벤트뿐입니다. 다른 블록이나 코어의 카운터가 필요하면
HAPTI_COUNTERS환경 변수로 지정하십시오.
설치¶
hapti는 개별 패키지로 제공되지 않으며, 컴파일러, 런타임, 프레임워크 통합 컴포넌트와 함께
단일 HyperAccel SDK wheel 패키지 형태로 배포됩니다. 자세한 설치 방법은
SDK 설치 가이드를 참고하십시오.
호환성¶
이 문서는 hapti 0.0.6 버전을 기준으로 작성되었습니다. 버전별 변경 사항은
릴리즈 노트에서 확인할 수 있습니다.
| 검증된 버전 | |
|---|---|
| Python | 3.10 – 3.12 |
Runtime (hart) |
0.0.6 |
| 트레이스 뷰어 | Perfetto UI, Chrome tracing |
자세한 명세는 지원 매트릭스를 참고하십시오.