콘텐츠로 이동

문제 상황의 진단 정보 모으기

카드가 응답하지 않거나(hang), FATAL이 되거나, 평소와 다르게 동작할 때 지원팀이 원인을 찾는 데 필요한 정보를 아카이브 하나로 모으는 방법을 설명합니다. 리셋은 고장을 설명하는 상태를 지우므로 이 페이지의 스크립트는 카드를 리셋하기 전에 실행합니다. 스크립트는 디바이스 노드를 열지 않고 상태를 읽기만 하므로, 워크로드가 도는 중에도 실행할 수 있습니다.


먼저 모으고, 그다음 복구합니다

실행 시점

헬스체크나 모니터링이 다음 가운데 하나를 알리면 카드에 조치를 취하기 전에 스크립트부터 실행합니다. 카드에 조치를 취한다는 것은 SDK로 요청하는 리셋, ha-hotreset, 모듈 재적재나 언바인드, 호스트 재부팅을 말합니다.

  • health가 faulted이거나 hyperaccel-smi의 Health가 FAULTED입니다.
  • devcmd_timeouts, devcmd_fw_errors, hdma_timeouts가 마지막으로 본 값보다 늘었습니다.
  • 커널 로그에 워치독 경고(watchdog: … wait stalled), Devcmd no response, Devcmd waiting, hang 덤프(hang (…), hang dump (…)), Firmware error, sys_mon: no response가 남았습니다.
  • 애플리케이션이 SDK에서 디바이스 오류를 받거나, 워크로드가 진행하지 않는데 inflight가 줄지 않습니다.
  • 온도, 전력, 사용률이 계속 unknown입니다.
  • 성능이 기대보다 낮아 문의합니다. 아카이브에 abi_prefetch_stats도 들어갑니다.

모은 뒤에는 카드 복구를 따릅니다.

조치하면 사라지는 기록

카드에 조치를 취하면 그 시점의 상태는 다시 볼 수 없습니다. 리셋하면 멈춘 작업이 끝나고 기록만 남으며, 남는 기록도 방법에 따라 다릅니다.

기록 디바이스 리셋(SDK 리셋, 자동 리셋) 카드를 다시 인식(ha-hotreset, 모듈 재적재, 언바인드 후 바인드) 호스트 재부팅
health의 faulted 풀립니다. 리셋이 실패하면 남습니다 풀립니다 풀립니다
오류 카운터 남습니다 0부터 다시 셉니다 0부터 다시 셉니다
last_hang 남습니다. 리셋 중 펌웨어가 응답하지 않으면 진행 필드(batch_seq, exec_index, resq_tail)와 판정(verdict)이, 펌웨어가 리셋 명령에 오류를 돌려주면 앞의 세 필드(rc, cmd_idx, opcode)가 그 리셋의 기록으로 바뀝니다 처음 상태로 돌아갑니다 처음 상태로 돌아갑니다
커널 로그 남지만, 뒤이어 남는 메시지가 앞선 줄을 밀어낼 수 있습니다 디바이스 리셋과 같습니다 커널 로그 버퍼가 비워집니다. systemd 저널을 영구 저장하는 경우에만 저널에 남습니다

모듈 재적재와 언바인드는 카드를 리셋하지 않으므로 멈춘 카드를 되살리지 못하지만, 드라이버의 기록은 이처럼 지웁니다. 복구 수단을 보십시오.

자동 리셋을 켠 장비

ha_auto_reset=1이면 드라이버가 FATAL 직후 스스로 리셋하므로 리셋 전 상태를 모을 기회가 없습니다. 알아챈 즉시 스크립트를 실행하십시오. 리셋 뒤에도 남는 커널 로그, 오류 카운터, last_hang이 진단의 근거가 됩니다.

스크립트는 이번 부팅의 커널 로그만 모읍니다. 호스트를 이미 재부팅했다면 sudo journalctl -k -b -1 > journal-prev.txt로 이전 부팅의 커널 로그를 따로 저장해 함께 보내십시오. 저널을 영구 저장하지 않는 호스트에서는 syslog 파일(예: /var/log/kern.log, /var/log/messages)에 이전 부팅의 커널 로그가 남아 있을 수 있습니다.


수집 스크립트

실행

아래 스크립트를 ha-collect-diag.sh로 저장하고 root 권한으로 실행합니다. 인자는 출력 디렉터리이며, 생략하면 현재 디렉터리에 만듭니다.

1
sudo sh ha-collect-diag.sh /var/tmp
1
saved: /var/tmp/ha-diag-20261008-153012.tar.gz

압축하기 전의 파일은 같은 이름의 디렉터리(/var/tmp/ha-diag-20261008-153012/)에 남습니다. 지원팀에는 .tar.gz 파일을 보냅니다. 호스트의 /sys가 다른 경로에 마운트된 환경(예: 컨테이너)에서는 SYSFS=/host/sys sh ha-collect-diag.sh처럼 그 경로를 SYSFS로 알려 줍니다. 컨테이너 안에서는 host.txt의 배포판 정보와 modinfo.txt가 컨테이너의 것이고 커널 로그가 빠지기 쉬우므로, 가능하면 호스트에서 root로 실행하십시오.

스크립트

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
#!/bin/sh
# ha-collect-diag.sh - LPU 진단 정보를 디렉터리 하나와 .tar.gz 하나로 모읍니다.
# 사용법: sudo sh ha-collect-diag.sh [출력 디렉터리] (기본값: 현재 디렉터리)
# 읽기만 합니다. sysfs에 쓰지 않고, /dev/haN을 열지 않으며, 아무것도 리셋하지 않습니다.

# 호스트의 /sys가 다른 경로에 마운트되어 있으면 SYSFS로 알려 줍니다.
SYSFS=${SYSFS:-/sys}
# 카드마다 읽을 노드. fw_update_progress와 help는 읽지 않습니다.
NODES="health devcmd_timeouts devcmd_fw_errors hdma_timeouts last_hang inflight
stream_count fw_version hw_version serial dram_size dram_used dram_free sram_size
sram_used sram_free temp temp_avg temp_blocks power_mw rails util
abi_prefetch_stats peer_map peer_route peer_sram tw_window_size dmabuf_exports
bypass_range_check"

# 호스트 정보가 들어가므로 실행한 사용자만 읽을 수 있게 만듭니다.
umask 077
base=${1:-.}
name=ha-diag-$(date +%Y%m%d-%H%M%S)
out=$base/$name
{ mkdir -p "$base" && mkdir "$out"; } || exit 1
[ "$(id -u)" -eq 0 ] || echo "not root: dmesg, journal and lspci output may be incomplete" >&2

# run <파일> <명령> [인자...]: 출력을 파일에 저장하고 결과를 status.txt에 적습니다.
run() {
    f=$1
    shift
    if ! command -v "$1" >/dev/null 2>&1; then
        echo "$f: missing ($1 not found)" >> "$out/status.txt"
    elif "$@" > "$out/$f" 2>&1; then
        echo "$f: ok" >> "$out/status.txt"
    else
        echo "$f: exit $?" >> "$out/status.txt"
    fi
}

# 1. 카드별 sysfs. 상태가 바뀌기 전에 가장 먼저 읽습니다.
cards=0
for d in "$SYSFS"/class/ha/ha*; do
    [ -d "$d" ] || continue
    cards=$((cards + 1))
    n=${d##*/}
    {
        echo "# $n $(basename "$(readlink -f "$d/device")")"
        for node in $NODES; do
            grep -H . "$d/$node" 2>&1
        done
        echo "iommu_group: $(basename "$(readlink "$d/device/iommu_group" 2>/dev/null || echo none)")"
        grep -H . "$d/device/iommu_group/type" 2>&1
    } > "$out/sysfs-$n.txt"
done
echo "sysfs: $cards card(s) under $SYSFS/class/ha" >> "$out/status.txt"

# 2. 호스트와 드라이버
{
    date
    uname -a
    cat /etc/os-release
} > "$out/host.txt" 2>&1
{
    grep -H . "$SYSFS/module/ha/version"
    grep -H . "$SYSFS"/module/ha/parameters/*
} > "$out/driver.txt" 2>&1
run lsmod.txt lsmod
run modinfo.txt modinfo ha

# 3. 이번 부팅의 커널 로그. 버퍼에서 밀려난 줄이 저널에 남아 있을 수 있어 둘 다 저장합니다.
run dmesg.txt dmesg -T
run journal.txt journalctl -k -b --no-pager

# 4. hyperaccel-smi. 위와 같은 sysfs에서 모든 카드를 보게 합니다.
unset HYPERACCEL_VISIBLE_DEVICES
run hyperaccel-smi-q.txt hyperaccel-smi --root "$SYSFS/class/ha" -q
run hyperaccel-smi.json hyperaccel-smi --root "$SYSFS/class/ha" --json

# 5. PCI. 20fb는 HyperAccel의 PCI 벤더 ID입니다.
run lspci-vvv.txt lspci -D -nn -vvv -d 20fb:
run lspci-tv.txt lspci -D -tv

# 6. 묶기
if (cd "$base" && tar -czf "$name.tar.gz" "$name"); then
    echo "saved: $out.tar.gz"
else
    echo "archive failed; files are in $out" >&2
    exit 1
fi

모으는 항목

파일 내용
sysfs-haN.txt 카드마다 하나. 첫 줄의 PCI 주소, NODES에 적힌 노드의 값, IOMMU 그룹 번호와 그 type
host.txt 수집 시각, uname -a, /etc/os-release
driver.txt 적재된 드라이버 버전(/sys/module/ha/version)과 모듈 파라미터의 현재 값
lsmod.txt, modinfo.txt 적재된 모듈 목록, 설치된 ha 모듈 파일의 정보
dmesg.txt 커널 로그 버퍼 전체
journal.txt systemd 저널에 남은 이번 부팅의 커널 로그
hyperaccel-smi-q.txt, hyperaccel-smi.json hyperaccel-smi -q와 --json의 출력
lspci-vvv.txt HyperAccel 카드(PCI 벤더 ID 20fb)의 PCI 설정 공간. 링크 상태와 오류 상태 레지스터가 들어 있습니다
lspci-tv.txt PCI 토폴로지
status.txt 찾은 카드 수와 명령마다의 결과

status.txt에는 명령마다 결과가 한 줄씩 남습니다. ok는 정상, missing은 그 명령이 호스트에 없어 건너뛴 것, exit <코드>는 명령이 0이 아닌 종료 코드로 끝난 것입니다. lspci는 pciutils 패키지에 들어 있고, hyperaccel-smi는 보이는 카드가 없으면 exit 2로 끝납니다. 읽지 못한 sysfs 노드는 sysfs-haN.txt의 그 자리에 오류 메시지로 남습니다. 어느 경우든 스크립트는 멈추지 않고 나머지를 모읍니다. IOMMU type 값의 뜻은 IOMMU 모드와 디바이스 간 경로를 보십시오.

읽지 않는 노드

스크립트는 읽을 노드를 이름으로 지정하며, 다음 두 노드는 읽지 않습니다.

노드 읽지 않는 이유
fw_update_progress 읽을 때마다 디바이스에서 직접 값을 읽습니다. 응답하지 않는 카드에서는 읽지 않아야 합니다
help 드라이버에 들어 있는 고정 설명문이라 카드의 상태를 담지 않습니다

디버그용 설정인 bypass_range_check는 텔레메트리가 아니지만, 값이 1이면 드라이버가 디바이스 메모리 접근 요청의 범위를 검사하지 않으므로 진단에 필요해 함께 모읍니다(bypass_range_check). 나머지 노드는 드라이버가 호스트 메모리에 유지하는 상태와 폴러가 모아 둔 값을 내므로, 읽어도 디바이스에 접근하지 않고 카드가 멈춘 동안에도 응답합니다. 예외는 fw_version과 serial입니다. fw_version이 unknown인 동안에는 두 노드를 읽을 때 펌웨어가 준비되었는지 다시 확인하며, 드라이버가 이 확인을 건너뛰는 조건은 모니터링 정지에 있습니다. 노드를 이름으로 지정하므로 드라이버 버전이 바뀌어 노드가 늘어도, 확인하지 않은 노드는 읽지 않습니다.

root 권한

root가 아니어도 스크립트는 끝까지 돌고, sysfs 노드, 모듈 파라미터, hyperaccel-smi, lspci -tv는 그대로 모입니다. 다음 세 항목은 root 권한이 없으면 비거나 일부만 남습니다. 이때 스크립트는 시작하면서 not root:로 시작하는 줄을 출력합니다.

  • dmesg.txt: 커널 설정 kernel.dmesg_restrict가 1이면 root(정확히는 CAP_SYSLOG 권한)가 아닌 사용자는 커널 로그 버퍼를 읽을 수 없습니다. 현재 값은 sysctl kernel.dmesg_restrict로 확인합니다.
  • journal.txt: root가 아니면 시스템 저널을 읽지 못해 커널 로그가 빠질 수 있습니다.
  • lspci-vvv.txt: root가 아니면 PCI 설정 공간의 앞 64바이트만 읽을 수 있어, 링크 상태와 오류 상태 대신 Capabilities: <access denied>가 나옵니다. 컨테이너 안에서는 root여도 같을 수 있습니다.

아카이브 읽기

지원팀에 보내기 전에 직접 확인할 것들입니다. 값의 뜻은 링크한 페이지에 있습니다. 카드마다의 파일은 다음과 같이 시작합니다.

1
2
3
4
5
6
# ha1 0000:65:00.0
/sys/class/ha/ha1/health:faulted
/sys/class/ha/ha1/devcmd_timeouts:1
/sys/class/ha/ha1/devcmd_fw_errors:0
/sys/class/ha/ha1/hdma_timeouts:0
/sys/class/ha/ha1/last_hang:rc=- cmd_idx=- opcode=- batch_seq=1041->1042 exec_index=0 resq_tail=0 verdict=stuck-in-command
  1. 카드 상태: health가 faulted면 디바이스가 FATAL이거나 마지막 리셋이 실패한 상태입니다. health 판정을 보십시오.
  2. 오류 카운터: devcmd_timeouts, devcmd_fw_errors, hdma_timeouts는 값 자체보다 지난번에 본 값에서 늘었는지를 봅니다. RAS 카운터를 보십시오.
  3. last_hang: verdict는 펌웨어가 배치의 어디에서 멈췄는지에 대한 판정입니다. 앞의 세 필드와 뒤의 네 필드는 서로 다른 사건의 기록일 수 있습니다. last_hang과 배치 진행 판정을 보십시오.
  4. 커널 로그: dmesg.txt에서 드라이버의 hang 기록을 찾습니다(아래 명령). hang (…) 줄은 사람이 읽는 요약이고 hang dump (…) 줄은 원본 값입니다. hang 덤프와 커널 로그 메시지를 보십시오.
  5. 빠진 항목: status.txt에 missing이나 exit가 있는지 봅니다. 커널 로그가 빠졌다면 root 권한으로 다시 실행합니다.
1
grep -E ' ha [0-9a-f]+:' dmesg.txt | grep -E 'watchdog|Devcmd|hang|Firmware error|sys_mon|auto-TDR|device reset failed|fw_update'

느린지 멈췄는지 가리기

커널 로그에 Devcmd waiting이 10초마다 이어지면 애플리케이션이 상한 없이 기다리는 중입니다. 스크립트를 20초 이상 간격을 두고 두 번 실행해 두 아카이브의 last_hang을 비교하십시오. batch_seq나 exec_index가 바뀌었다면 디바이스는 진행 중입니다. 상한 없는 대기를 보십시오.


보내기 전에 확인할 것

아카이브에는 진단에 필요한 만큼 호스트 정보가 들어 있습니다.

  • 호스트 이름과 커널, 배포판 버전(host.txt), 적재된 모듈 목록, PCI 장치 목록과 설정이 들어 있습니다.
  • 커널 로그(dmesg.txt, journal.txt)에는 이 드라이버와 관계없는 장치와 서비스의 메시지도 모두 들어 있습니다. hang 기록의 opened by pid <PID> (<이름>)에는 카드를 연 프로세스의 이름이 남습니다.
  • 스크립트가 만든 디렉터리와 아카이브는 스크립트를 실행한 사용자만 읽을 수 있습니다. sudo로 실행했다면 읽거나 복사할 때도 root 권한이 필요합니다.

보내기 전에 내용을 확인하십시오. 조직의 정책상 가려야 할 값이 있으면 디렉터리의 파일에서 줄을 지우지 말고 그 값만 바꾼 뒤, 아카이브를 다시 만드십시오(sudo sh -c 'umask 077; cd /var/tmp && tar -czf ha-diag-<시각>.tar.gz ha-diag-<시각>'). 스크립트가 처음 만든 아카이브에는 바꾸기 전의 값이 그대로 들어 있습니다. 원인이 드라이버 메시지보다 앞선 다른 줄(예: 상위 PCIe 포트의 오류)에 있는 경우가 있어, 줄을 골라내면 진단하기 어려워집니다. 아카이브와 함께 알려 줄 내용(증상이 시작된 시각, 그때 돌던 작업, 재현 절차)은 지원 요청에 있습니다.


함께 보기