콘텐츠로 이동

7. 문제 해결 (Troubleshooting)

원인을 성급히 추론하기 전에, 콘솔에 출력된 에러 메시지나 트레이스 뷰어에서 확인한 증상을 본 문서에서 먼저 검색해 보십시오.

본 장의 각 항목은 증상, 원인, 조치의 3단 구조로 기술되어 있습니다. 원인을 함께 명시한 이유는 문서에 없는 유사한 문제를 마주했을 때 스스로 판단할 수 있는 기술적 근거를 제공하기 위함입니다. 본 장에서 다루는 대부분의 현상은 2장 트레이스 수집부터 4장 트레이스 데이터 분석 가이드까지 설명한 메커니즘이 실제 증상으로 발현된 것입니다. 동일한 증상이 반복될 경우 해당 장을 다시 참고하십시오.

Contents

Section Objective
시작하기 전에 문제 해결 및 기술 지원 요청 전 수집해야 할 기본 진단 정보
트레이스 파일이 없음 파일 미생성, 누락 및 멀티 프로세스 환경 대처 방안
비어 있거나 일부만 있는 트레이스 디바이스 트랙, 카운터, 주석 누락 대응 및 클럭 동기화 오류 조치
옵션 및 명령어 관련 CLI 플래그 미적용, 파일 경로 지정 오류 및 병합(Merge) 오류
이상해 보이는 숫자 카운터, 대역폭, 활용률 및 오버헤드 수치 검증
트레이스가 열리지 않음 Perfetto 파일 거부 현상 및 JSON 용량 초과 대응
실행 간섭 현상 LD_PRELOAD 환경 충돌 및 종료 코드(Exit Code) 제어
지원 요청 문제 미해결 시 HyperAccel 지원팀 전달 항목

시작하기 전에

지원 요청 시 아래 진단 정보를 함께 수집해 주십시오. 기술 지원 시 가장 먼저 확인하는 핵심 항목들입니다.

1
2
3
4
which haprof
python -c "import hapti; print(hapti.__file__)"
ls -la *.pftrace *.json 2>/dev/null
env | grep -E '^HAPTI_|^HA_PROFILE_|^LD_PRELOAD'

트레이스 파일이 없음

아무것도 생성되지 않음

증상 — 프로그램 실행이 완료되었음에도 .pftrace 및 .json 결과 파일이 전혀 생성되지 않습니다.

원인 — 프로세스가 비정상 강제 종료되었거나, 출력 디렉토리 경로를 오인했거나, 필수 도구 라이브러리가 누락되었을 가능성이 높습니다.

조치

  1. 프로세스 강제 종료 여부 확인 — 트레이스 데이터는 프로세스가 정상적으로 종료될 때 파일로 일괄 기록됩니다. SIGKILL, 치명적 세그멘테이션 크래시, 컨테이너 강제 중지 등의 상황에서는 데이터가 남지 않습니다. 프로세스를 강제로 종료하지 말고 인터럽트 시그널을 보내 정상 종료시키십시오.
  2. 출력 경로 확인 — 기본 저장 위치는 haprof를 실행한 작업 디렉토리이며, -d 옵션을 지정한 경우 해당 경로에 생성됩니다.
  3. 도구 라이브러리 존재 여부 확인 — 필수 라이브러리가 누락된 경우 haprof가 libhapti_tool.so 탐색 실패 에러를 출력하며 실행 직전에 종료됩니다. 이 경우 HyperAccel SDK를 다시 설치하십시오.

멀티 프로세스 실행 시 트레이스가 하나만 생성됨

증상 — 멀티 랭크 분산 실행 환경인데 트레이스 파일 쌍이 오직 하나만 생성됩니다.

원인 — 자식 프로세스는 기본적으로 프로파일링 대상에서 제외됩니다. 자식 프로세스가 중복 트레이스를 생성하는 것을 방지하기 위해 도구가 시작 시 센티넬(Sentinel) 변수를 해제하기 때문입니다.

조치 — --profile-children 옵션을 지정하여 실행하십시오. 각 랭크별로 <hostname>_<pid>_<starttime> 파일 쌍이 개별적으로 생성됩니다.


비어 있거나 일부만 있는 트레이스

디바이스 트랙이 비어 있음

증상 — 호스트 API 호출 내역은 정상적으로 표시되는데 LPU Device 트랙에 커널이나 메모리 전송 슬라이스가 나타나지 않습니다.

원인 — 디바이스 트레이싱 옵션이 활성화되지 않았거나 디바이스 프로파일링 설정이 거부되었습니다.

조치

  1. --runtime-trace 또는 --device-trace 플래그를 인자로 전달했는지 확인하십시오. 옵션이 없으면 설계상 호스트 측만 기록됩니다.
  2. 표준 에러(stderr) 출력에서 다음 문자열을 확인하십시오.

    진단 메시지 근본 원인 조치 사항
    S6 DEVICE RECORDS DISABLED (configure rc=...) 드라이버 및 펌웨어가 프로파일링을 지원하지 않음 프로파일링을 지원하는 최신 드라이버 및 펌웨어로 업그레이드
    no LPU device to profile / HaSetDevice(N) failed 프로파일링 대상 디바이스를 찾지 못함 HAPTI_TOOL_DEVICE_ID에 지정한 디바이스 번호가 유효한지 확인
    device timeline: device reset or teardown before setup 디바이스 리셋 또는 런타임 종료가 프로파일링 설정보다 먼저 발생함 리셋 이후의 구간을 프로파일하려면 리셋 시점 뒤에서 새로 실행
  3. 프로그램이 디바이스 연산 완료 전에 종료되는 경우, 아직 완료되지 않은 배치의 레코드는 존재하지 않습니다. 프로그램 종료 직전에 스트림 동기화를 명시적으로 수행하십시오 (디바이스 트레이싱: 디바이스 레코드가 수집되는 시점 참고).

커널 위치가 터무니없음

증상 — 커널 슬라이스가 호스트 타임라인과 전혀 맞지 않는 시각(아주 먼 과거나 미래)에 표시됩니다.

원인 — 디바이스 사이클을 나노초로 변환하는 클럭 동기화(Clock Sync)에 실패하여 커널 타임스탬프가 원시 사이클(Raw Cycle) 값으로 잔류했기 때문입니다. stderr에 kernel clock_sync=FAILED(kernel ts left raw)가 기록됩니다.

조치 — 사용 중인 드라이버와 펌웨어가 클럭 동기화를 지원하는 버전인지 지원 매트릭스에서 확인하십시오. 클럭 동기화가 실패한 상태의 커널 시각은 호스트 레코드와 비교할 수 없습니다.

디바이스 타임라인에 공백이 있음

증상 — 커널이 존재해야 할 타임라인 구간이 비어 있으며, 프로세스 종료 시 [hapti-tool] 경고 메시지가 출력됩니다.

원인 — 레코드가 리더 스레드에 의해 수거되기 전에 오버런(Overrun) 등으로 인해 유실되었습니다.

조치 — 디바이스 트레이싱: 비용과 유실의 경고 메시지 대응 표를 참고하십시오. 짧은 커널이 매우 고빈도로 실행되는 경우 프로파일링 대상 구간을 좁혀서 수집하십시오.

한 디바이스의 활동만 보임

증상 — 멀티 디바이스 환경에서 실행 중인 프로세스인데 타임라인에 디바이스 트랙이 하나만 나타납니다.

원인 — 디바이스 레코드는 세션당 하나의 디바이스에서만 수집되며, 기본값은 인덱스 0번입니다.

조치 — HAPTI_TOOL_DEVICE_ID 환경 변수로 다른 디바이스 인덱스를 지정하거나, 멀티 랭크 실행 시 --profile-children 옵션을 사용하여 각 랭크가 자신만의 디바이스를 개별 프로파일링하도록 설정하십시오.

사용자 Python 코드가 보이지 않음

증상 — Python 함수나 모델 내부 단계가 트레이스 타임라인에 나타나지 않습니다.

원인 — 프로파일러는 Python 인터프리터 내부가 아니라 런타임 API와 그 하위 계층 호출을 가로챕니다.

조치 — 분석하고자 하는 주요 코드 구간에 주석(Annotation)을 명시적으로 추가하십시오 (5장 주석 참고).

--device-trace를 지정했으나 원하는 하드웨어 카운터가 없음

증상 — 커널 슬라이스는 정상 수집되었으나 CGDMA, MPU 카운터 또는 core 1 이상의 수치가 표시되지 않습니다.

원인 — 기본 설정은 core 0의 AXIBRG, DMC, UTIL 등 총 20개 핵심 이벤트만 등록합니다. 커널 슬라이스 자체가 없다면 위 항목의 "디바이스 트랙이 비어 있음"과 동일한 원인입니다.

조치 — HAPTI_COUNTERS 환경 변수를 사용하여 필요한 이벤트를 직접 지정하십시오. 유효하지 않은 토큰은 stderr에 [ha_profiling] HAPTI_COUNTERS: unknown ... — skipped로 출력되고 안전하게 무시됩니다.

torch.profiler 트레이스에 런타임 API 호출이 없음

증상 — Kineto 플러그인으로 수집한 트레이스에 Ha* 런타임 API 호출과 디바이스 활동이 나타나지 않습니다.

원인 — 한 프로세스 내에 hart 런타임이 중복 로드된 경우(예: 서로 다른 환경에 설치된 hart를 함께 불러오는 경우), 플러그인이 애플리케이션이 실제로 사용하는 런타임 인스턴스가 아닌 다른 인스턴스에 연결되었습니다.

조치 — 프로세스가 단일 환경에 설치된 hart 모듈만 불러오도록 환경을 정돈하십시오. ProfilerActivity.PrivateUse1 활동이 수집 목록에 포함되어 있는지도 함께 확인하십시오 (프로파일링 실행 참고).

torch.profiler 트레이스에 hapti 주석이 나타나지 않음

증상 — Kineto 플러그인으로 수집한 트레이스에 hapti.annotate() 구간이 포함되어 있지 않습니다.

원인 — Kineto 수집 경로는 hapti 주석 활동을 수집하지 않는 구조입니다.

조치 — PyTorch 표준인 torch.profiler.record_function()을 대신 사용하십시오 (PyTorch 프로파일러 연동 참고).


옵션 및 명령어 관련

--kernel-trace 등 도메인별 플래그가 동작하지 않음

증상 — --kernel-trace, --driver-trace 등의 옵션을 주어도 트레이스 내용에 변화가 없습니다.

원인 — 도메인별 플래그는 파싱만 되고 아직 도구로 전달되지 않습니다. 호스트 측 활동은 플래그와 관계없이 항상 전부 수집됩니다.

조치 — 디바이스 데이터 수집 여부는 --runtime-trace 또는 --device-trace 옵션으로 제어하십시오. 옵션별 상세 지원 현황은 CLI 레퍼런스를 참고하십시오.

must be a bare file name, not a path

증상 — haprof -o traces/run1 -- ... 형태의 명령어가 실행 전에 거부됩니다.

원인 — -o 옵션은 디렉토리 경로를 포함하지 않는 순수 파일 이름만 인자로 받습니다. 디렉토리 지정은 -d 옵션의 전용 역할입니다.

조치 — haprof -d traces -o run1 -- ...과 같이 디렉토리와 파일 이름을 나누어 지정하십시오.

--profile-children without the json format

증상 — -f pftrace --profile-children 조합으로 실행하면 경고 메시지가 출력됩니다.

원인 — haprof merge의 Straggler 리포트가 각 랭크 트레이스의 .json 파일을 읽어 분석하기 때문입니다.

조치 — Straggler 리포트가 필요한 경우 -f 옵션에 json을 함께 포함하십시오. 병합된 타임라인만 필요한 경우 해당 경고는 무시해도 무방합니다.

[haprof merge] error: no traces found

증상 — haprof merge 실행 시 대상 트레이스를 찾지 못하고 종료됩니다.

원인 — -d 옵션 경로(기본값: 현재 디렉토리)에 랭크별 트레이스 파일이 존재하지 않습니다.

조치 — 트레이스 파일이 실제로 저장된 디렉토리를 -d로 명시하거나 대상 파일들을 인자로 직접 전달하십시오.


이상해 보이는 숫자

첫 실행 회차의 카운터 값이 비어 있거나 비정상적으로 큼

증상 — 최초 커널 실행의 하드웨어 카운터 값이 이후 실행 값보다 월등히 높거나 왜곡되어 나타납니다.

원인 — Free-running 하드웨어 카운터는 직전 실행 회차와의 차분으로 계산됩니다. 첫 실행 회차에는 유효한 직전 기준값이 존재하지 않기 때문에 프로파일링 시작 전에 수행되던 작업의 누적값이 섞여 들어갑니다.

조치 — 충분한 워밍업(Warm-up) 단계를 거친 뒤 안정화된 상태(Steady-state)의 회차를 분석 대상으로 삼고, 첫 실행 결과는 폐기하십시오.

CGDMA 대역폭이 직접 계산한 값과 다름

증상 — 커널의 CGDMA.c<n>.read BW (GB/s)·CGDMA.c<n>.write BW (GB/s) 지표가 전송 바이트 수와 소요 시간으로 산출한 대역폭 값과 일치하지 않습니다.

원인 — 해당 카운터 값은 실측된 바이트 수가 아니라 펌웨어가 정의한 피크 성능 기준으로 스케일링된 활용률 지표입니다. 반면 전송 슬라이스의 memory bandwidth (GB/s)는 실측 기반 값입니다.

조치 — 커널 대역폭 지표는 절대적인 전송 속도가 아니라 회차 간 상대적 성능 비교 용도로만 활용하십시오(카운터 레퍼런스: 표시 규칙 참고).

활용률(Utilization)이 체감보다 낮게 나옴

증상 — 부하가 높을 것으로 예상한 유닛의 UTIL.*% 지표가 지나치게 낮게 나옵니다.

원인 — UTIL 카운터는 사이클 단위의 정밀 측정이 아니라 샘플링 기반으로 집계됩니다. 샘플과 샘플 사이의 짧은 버스트 형태로 동작하고 종료되는 유닛은 낮게 측정됩니다.

조치 — 활용률 지표는 듀티 사이클(Duty Cycle) 추정치로 간주하고, Stall 분해 지표와 교차 대조하여 검증하십시오.

프로파일한 실행이 훨씬 느림

증상 — haprof 환경에서 애플리케이션을 실행할 때 전체 수행 시간이 크게 늘어납니다.

원인 — 예상된 프로파일러 오버헤드입니다. 특히 소형 커널이 고빈도로 실행되는 워크로드에서 --device-trace 모드를 활성화할 경우, 호출당 고정 오버헤드가 누적되어 전체 소요 시간이 크게 늘어납니다.

조치 — 시간이 어디에서 소요되는지 진단할 때는 프로파일링을 적용한 실행 결과를 활용하고, 실제로 얼마나 빨라졌는지를 측정할 때는 반드시 프로파일러 없이 실행한 순수 Wall-clock 결과를 비교하십시오.


트레이스가 열리지 않음

Perfetto가 파일을 거부함

증상 — ui.perfetto.dev 웹 뷰어에서 트레이스 파일을 열지 못하거나 일부 구간만 표시됩니다.

원인 — 대개 프로세스가 비정상 종료되면서 파일 출력 종료 처리가 누락되어 파일이 잘렸기 때문입니다.

조치 — 생성된 파일의 용량을 확인하고, 프로그램을 다시 실행하여 정상 종료시킨 새로운 트레이스 파일로 열어 보십시오.

JSON 트레이스 파일이 너무 큼

증상 — 생성된 .json 파일 용량이 지나치게 커서 chrome://tracing 브라우저가 멈추거나 매우 느려집니다.

원인 — Chrome JSON 포맷은 구조적으로 매우 장황하며, 디바이스 트레이싱이 활성화된 장시간 실행은 대규모 레코드를 생성하기 때문입니다.

조치 — 가급적 .pftrace(Perfetto Protobuf) 바이너리 형식을 사용하십시오. 필요에 따라 -f pftrace 옵션으로 JSON 생성을 생략하거나, 주석(Annotation)을 활용하여 프로파일링 수집 구간을 좁히십시오.


실행 간섭 현상

haprof 환경에서 애플리케이션 동작이 달라짐

증상 — 프로파일러 없이 실행할 때는 문제없던 라이브러리 로딩이나 초기화 과정이 haprof 적용 시 실패합니다.

원인 — 프로파일러는 LD_PRELOAD 메커니즘을 사용하며, 런타임 라이브러리가 단일 매핑으로 해석되도록 패키지 디렉토리를 라이브러리 검색 경로 맨 앞에 추가합니다. 자체적인 LD_PRELOAD를 사용하거나 특수한 라이브러리 배치 구조를 가진 프로그램의 경우 충돌이 발생할 수 있습니다.

조치 — 사용자가 직접 LD_PRELOAD 환경 변수를 설정하지 말고, haprof의 --preload 옵션을 통해 추가 라이브러리를 전달하십시오. 그래야 올바른 라이브러리 로딩 순서가 유지됩니다.

프로세스 종료 코드(Exit Code)가 기대와 다름

증상 — haprof를 감싸는 상위 셸 스크립트가 대상 프로그램의 종료 코드를 기대한 대로 전달받지 못합니다.

원인 — haprof는 기본적으로 execvpe 시스템 콜을 사용하여 자기 자신의 프로세스 이미지를 대상 명령어로 직접 교체하므로, 최종 종료 코드는 대상 프로그램의 것을 그대로 따릅니다. 별도의 서브프로세스 경계가 필요한 래퍼 스크립트에서는 의도와 다를 수 있습니다.

조치 — --no-execv 옵션을 사용하여 대상을 별도의 자식 프로세스로 실행하고 종료 코드를 명시적으로 전파하도록 설정하십시오.


지원 요청

위의 문제 해결 항목으로도 이슈가 해결되지 않는 경우, 아래 진단 정보를 빠짐없이 첨부하여 HyperAccel 지원팀에 문의해 주십시오.

  1. 시작하기 전에 섹션에서 수집한 기본 진단 정보 출력 결과
  2. 실행한 전체 haprof 명령어 및 --log-level info 옵션을 추가해 재실행한 표준 에러(stderr) 출력 전체
  3. 트레이스 파일 생성 여부 및 생성된 결과 파일의 용량
  4. 사용 중인 HyperAccel SDK 버전 정보(pip show hapti)
  5. 프로파일러를 적용하지 않은 상태에서 프로그램이 정상 종료하는지 여부