haprof CLI¶
1 2 | |
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 | |
| 형식 | 뷰어 |
|---|---|
.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 | |