콘텐츠로 이동

haprof CLI

1
2
haprof [옵션] -- <애플리케이션> [인자...]
haprof merge [옵션] [트레이스...]

haprof는 애플리케이션을 프로파일러 아래에서 실행하고, haprof merge는 랭크별 트레이스를 하나로 합칩니다. 첫 번째 형태에서 --는 프로파일러 옵션과 명령을 구분하며 생략할 수 없습니다. 옵션을 언제 쓰는지는 트레이스 수집에서 다룹니다.

Contents

Section Objective
1. 옵션 상태 각 옵션의 효과와 동작 여부
2. 출력 파일 이름 규칙과 형식
3. 종료 코드 무엇의 종료 코드인가
4. 랭크별 트레이스 병합 haprof merge를 이용한 병합과 Straggler 리포트
5. 예제 자주 쓰는 명령

1. 옵션 상태

범례 — ✅ 동작 · ❌ 파싱되지만 무시

무시되는 옵션은 경고 없이 지나갑니다

❌ 옵션은 명령줄에서 받아들여지지만 프로파일러로 전달되지 않습니다. 경고나 에러 없이 해당 플래그가 없는 것처럼 실행되므로, 사용하기 전에 아래 표를 확인하십시오.

트레이싱 옵션

옵션 상태 효과
--runtime-trace ✅ 디바이스 커널·메모리 전송 타임라인 추가
--device-trace ✅ 위에 더해 커널별 하드웨어 카운터와 시그널 로거. --runtime-trace 포함
--sys-trace ❌ 무시됨
--kernel-trace ❌ 무시됨
--memory-copy-trace ❌ 무시됨
--memory-allocation-trace ❌ 무시됨
--driver-trace ❌ 무시됨
--overhead-trace ❌ 무시됨
--external-correlation ❌ 무시됨
--marker-trace ❌ 무시됨

도메인별 플래그는 아직 도구로 전달되지 않습니다. 호스트 측 활동 종류인 런타임(메모리 할당 포함), 드라이버, 마커, 외부 상관관계는 플래그와 관계없이 항상 전부 수집되고, 디바이스 커널·메모리 전송은 --runtime-trace나 --device-trace로만 켜집니다. 프로파일러 자체의 실행 오버헤드는 아직 별도의 활동 레코드로 기록되지 않습니다.

출력 옵션

옵션 상태 효과
-d, --output-directory ✅ 트레이스를 쓸 디렉토리. 기본 .(haprof를 실행한 위치). 절대 경로로 바뀌어 전달되므로 대상이 chdir해도 유지
-o, --output-file ✅ 확장자 없는 파일 이름. 경로를 주면 거부. 기본 <hostname>_<pid>_<starttime>. --profile-children이면 접두어가 되어 <이름>_<hostname>_<pid>_<starttime>
-f, --output-format ✅ pftrace, json의 쉼표 구분 부분집합 또는 all(기본). 알 수 없는 형식은 거부
--log-level ✅ 도구 로그 레벨 error / warning(기본) / info

프로세스 제어 옵션

옵션 상태 효과
--profile-children ✅ 대상이 fork·exec한 자식 프로세스까지 프로파일. 프로세스별로 트레이스 생성. -f에 json이 없으면 경고
--preload ✅ 도구 라이브러리보다 먼저 LD_PRELOAD에 올릴 라이브러리 경로(콜론 : 구분)
--no-execv ✅ 런처를 대상 명령으로 교체(execv)하지 않고 서브프로세스로 실행. 종료 코드를 그대로 전달

디바이스 선택 설정과 같이 별도의 CLI 플래그가 제공되지 않는 세부 설정 항목들은 환경 변수를 통해 제어할 수 있습니다.


2. 출력 파일

프로파일된 프로세스마다 다음 파일이 생깁니다(-f, -o, -d로 변경 가능).

1
2
<hostname>_<pid>_<starttime>.pftrace
<hostname>_<pid>_<starttime>.json
형식 뷰어
.pftrace ui.perfetto.dev. 권장
.json chrome://tracing과 다른 Chrome 트레이스 도구. haprof merge 리포트의 입력

두 파일은 같은 레코드에서 생성됩니다. 이름에 시작 시각이 들어가는 것은 긴 실행에서 재사용된 pid가 앞선 랭크의 트레이스를 덮어쓰지 않게 하기 위해서입니다.

프로세스 종료 시 기록됩니다

SIGKILL로 죽었거나 종료 경로를 실행하지 못한 프로세스는 쓸 만한 트레이스를 남기지 않습니다.


3. 종료 코드

haprof는 execvpe로 자신을 대상으로 교체하므로 프로세스의 종료 코드는 대상의 것입니다. --no-execv를 쓰면 대상이 서브프로세스로 실행되고 종료 코드가 명시적으로 전달됩니다.

-- 뒤에 명령이 없거나, 도구 라이브러리가 없거나, 옵션 값이 잘못되면(-o에 경로, -f에 알 수 없는 형식 등) 실행 전에 0이 아닌 코드로 종료합니다.


4. 랭크별 트레이스 병합

멀티 랭크 실행 환경에서는 프로세스마다 독립된 트레이스 파일이 각각 생성됩니다. haprof merge 명령어는 --profile-children 옵션으로 수집된 랭크별 트레이스 파일들을 하나의 타임라인으로 병합하고, 동일한 집합 통신(Collective) 구간별로 랭크별 진입 지연을 분석하여 지연된 랭크(Straggler) 진단 리포트를 생성합니다.

명령어 옵션

옵션 기본값 효과
트레이스... -d 경로 내 모든 트레이스 병합 대상 파일 지정
-d, --directory . 트레이스 파일을 탐색할 디렉토리 경로
-o, --output merged.pftrace 병합된 최종 트레이스 파일 저장 경로
--no-trace — 병합된 트레이스 파일 없이 리포트만 생성
--report 포맷별 상이(text는 표준 출력, json은 straggler.json) 리포트 출력 경로
--report-format text 리포트 형식 지정(text, json, both)
--top 20 text 리포트에 나열할 주요 집합 통신 연산 개수

결과물 사양

결과물 종류 입력 소스 내용
병합된 .pftrace 랭크별 .pftrace 파일들 클럭 기준점이 이른 순서대로 이어 붙인 단일 타임라인. 각 랭크별로 별도의 레인(Lane) 배치
Straggler 리포트 랭크별 .json 파일들 집합 통신별 진입 지연(Entry skew), 소요 시간 편차, 마지막 도착·종료 랭크, 랭크별 지연 빈도 히스토그램

다중 장비 간 클럭 차이 주의사항

동일 장비 내에서 수집된 트레이스는 시스템 클럭을 공유하므로 정확하게 정렬됩니다. 만약 서로 다른 장비의 트레이스를 병합하는 경우, 리포트 상단에 장비 간 병합(cross-node: yes)임을 알리는 경고와 함께 프로세스별 클럭 오프셋이 출력됩니다. 클럭 자체는 별도 보정되지 않으므로, 이 오프셋들의 편차가 리포트에 표시되는 모든 지연 시간 분석의 오차 범위가 됩니다.


5. 예제

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# 호스트 측만
haprof -- python infer.py

# 디바이스 타임라인
haprof --runtime-trace -- python infer.py

# 디바이스 타임라인 + 하드웨어 카운터
haprof --device-trace -- python infer.py

# 위치·이름·형식 지정 → traces/decode.pftrace
haprof -d traces -o decode -f pftrace --device-trace -- python infer.py

# 멀티 랭크. 랭크마다 트레이스 하나, 이후 병합
haprof --profile-children --device-trace -d traces -- torchrun --nproc-per-node 4 serve.py
haprof merge -d traces -o traces/merged.pftrace --report-format both

# 0이 아닌 디바이스 선택 (CLI 플래그가 없습니다)
HAPTI_TOOL_DEVICE_ID=1 haprof --device-trace -- python infer.py

함께 보기