콘텐츠로 이동

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)을 관찰하며, 다음 세 부분으로 구성됩니다.

  • 진입점: 코드 수정 없이 실행하는 haprof CLI, torch.profiler에 통합하는 Kineto 플러그인, 코드 구간을 표시하는 Python 주석
  • 수집 범위: 호스트 API 활동(런타임 API와 하위 계층 호출), 디바이스 활동(커널·메모리 전송), 하드웨어 카운터와 시그널 로거
  • 타임라인 통합: 수집한 호스트 활동과 디바이스 활동을 하나의 타임라인으로 통합

각 기능의 요약은 hapti의 핵심 특징을 참고하십시오.

상위 계층이 hart 런타임과 LPU에서 실행되는 동안, hapti가 haprof CLI, Kineto 플러그인, Python 주석으로 호스트 API 활동과 디바이스 활동, 하드웨어 카운터를 관찰해 하나의 타임라인으로 통합하는 구조

소프트웨어 스택에서의 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
haprof -- python your_script.py

실행 시 작업 디렉토리에 <hostname>_<pid>_<starttime>.pftrace 및 .json 파일이 생성됩니다. 생성된 .pftrace 파일은 ui.perfetto.dev에서 열람할 수 있습니다.

디바이스 실행 기록과 커널별 하드웨어 카운터까지 함께 수집하려면 아래 옵션을 추가하십시오.

1
haprof --device-trace -- python your_script.py

분석 시 주의사항

  • 도메인별 트레이스 플래그는 아직 동작하지 않습니다. --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

자세한 명세는 지원 매트릭스를 참고하십시오.


문서

  • 📋 릴리즈 노트

    버전별 변경 사항, 폐기 예정 항목, 알려진 문제.