콘텐츠로 이동

카드 상태 헬스체크 만들기

호스트의 LPU 카드를 쓸 수 있는지 판정하는 셸 스크립트 ha-healthcheck.sh를 만들고, systemd 타이머와 모니터링 에이전트에서 주기적으로 실행하도록 연결합니다. 스크립트는 드라이버가 sysfs에 공개하는 파일만 읽으므로 root 권한과 디바이스 핸들이 필요 없고, 카드를 리셋하거나 작업을 보내지 않습니다. 결과는 카드마다 한 줄로 출력하고, 호출한 쪽은 종료 코드로 판정합니다.


확인할 항목

항목 읽는 파일 정상 정상이 아닐 때
드라이버 적재 /sys/module/ha/version 드라이버 버전(예: 2.6.0) 파일이 없으면 드라이버가 적재되지 않았습니다
카드 수 /sys/class/ha/haN 꽂은 카드 수만큼 있습니다 드라이버가 인식하지 못한 카드가 있습니다
카드 상태 /sys/class/ha/haN/health ok 아래 표를 보십시오
펌웨어 준비 /sys/class/ha/haN/fw_version major.minor.patch 형식의 버전 unknown이면 펌웨어가 준비되지 않았거나 드라이버가 버전을 읽지 못했습니다

health는 드라이버가 내리는 한 단어 판정입니다. 스크립트는 값마다 다음과 같이 판정합니다.

health 뜻 판정
ok FATAL도 리셋 실패도 없고, 오류 카운터가 모두 0입니다 OK
degraded 드라이버가 카드를 인식한 뒤 시간 초과나 펌웨어 오류가 한 번 이상 있었습니다. devcmd_timeouts, devcmd_fw_errors, hdma_timeouts 중 하나가 0이 아닙니다 WARN(-s를 주면 FAIL)
faulted 카드가 FATAL이거나 마지막 리셋(SDK 리셋이나 자동 리셋)이 실패했습니다 FAIL
unknown 드라이버가 상태를 읽을 수 없습니다. 카드 인식이 끝난 뒤에는 나오지 않습니다 FAIL

판정 기준을 이렇게 정한 이유는 다음과 같습니다.

  • degraded는 기본으로 실패로 보지 않습니다. 오류 카운터는 줄지 않으므로 degraded는 드라이버가 카드를 다시 인식할 때(핫 리셋, 모듈 재적재, 재부팅)까지 남고, SDK로 리셋해도 풀리지 않습니다. 애플리케이션이 보낸 잘못된 요청을 펌웨어가 거절한 경우도 devcmd_fw_errors에 셉니다. 그래서 degraded를 실패로 보면 오류가 한 번만 있었어도 그 뒤로 헬스체크가 계속 실패합니다. 문제가 계속되는지는 카운터가 늘어나는지로 판단하십시오(경보 기준). 카운터가 0에서 시작하는 설치 직후나 핫 리셋 직후에 확인할 때는 -s를 주어 degraded도 실패로 보십시오.
  • fw_version도 확인합니다. health는 펌웨어 준비 여부를 판정에 넣지 않으므로, 펌웨어가 준비되지 않은 카드도 ok일 수 있습니다.
  • 카드 수를 따로 확인합니다. 드라이버가 인식하지 못한 카드는 /sys/class/ha/ 아래에 나타나지 않으므로, 있는 카드의 health만 보아서는 빠진 카드를 알 수 없습니다.

헬스체크가 보지 않는 것

health는 진행 중인 정체를 바로 보여 주지 않습니다. 카드가 멈춰도 응답 대기 상한이 지나 시간 초과가 기록되기 전까지는 바뀌지 않습니다. 애플리케이션이 상한 없이 기다리도록 요청한 대기는 시간 초과로 기록되지 않으므로, 그 대기가 멈춰 있는 동안에는 계속 바뀌지 않습니다(커널 로그의 Devcmd waiting으로 알 수 있습니다). 온도, 전력, 텔레메트리 폴링 상태도 판정에 들어가지 않습니다. 이것들은 hang 감지와 워치독과 모니터링 연동을 따라 따로 감시하십시오.


sysfs만 읽는 이유

  • 디바이스 핸들과 root 권한이 필요 없습니다. /dev/haN을 열지 않으므로 워크로드와 카드를 두고 경쟁하지 않고, 워크로드가 카드를 쓰는 동안에도 실행할 수 있습니다. 텔레메트리 노드와 /sys/module/ha/version은 모든 사용자가 읽을 수 있습니다.
  • 카드가 멈춘 동안에도 값을 읽을 수 있습니다. health와 오류 카운터는 드라이버가 호스트 메모리에 유지하는 상태에서 계산하므로 계산 작업이 멈춘 동안에도 응답합니다. fw_version은 드라이버가 읽어 둔 값이며, 값이 unknown인 동안에만 읽을 때 펌웨어 준비 여부를 다시 확인합니다(수집 주기와 비용).
  • 카드를 리셋하거나 작업을 보내지 않습니다. 파일을 읽기만 합니다. fw_version이 unknown인 카드에서는 읽을 때 드라이버가 펌웨어 준비 여부를 다시 확인하고, 준비되었으면 값을 채웁니다. 드라이버의 폴러가 주기적으로 하는 확인과 같은 동작입니다.

스크립트

아래 내용을 ha-healthcheck.sh로 저장합니다. POSIX sh 문법만 쓰므로 bash가 아닌 /bin/sh(예: dash)에서도 돕니다.

 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
#!/bin/sh
# ha-healthcheck.sh: HyperAccel LPU 카드 상태를 sysfs에서 읽어 판정합니다.
# 사용법: ha-healthcheck.sh [-n 카드 수(1-8, 기본 1)] [-s(degraded도 FAIL)]
# 종료 코드: 0 정상, 1 FAIL인 카드 있음, 2 드라이버 없음 또는 카드 부족, 3 잘못된 옵션
# 환경 변수 SYSFS: sysfs 경로(기본 /sys)

usage() {
  echo "usage: ${0##*/} [-n COUNT] [-s]" >&2
  exit 3
}

expect=1
on_degraded=WARN
while getopts n:s opt; do
  case $opt in
    n) expect=$OPTARG ;;
    s) on_degraded=FAIL ;;
    *) usage ;;
  esac
done
shift $((OPTIND - 1))
[ $# -eq 0 ] || usage
case $expect in
  [1-8]) ;;
  *) usage ;;
esac

SYSFS=${SYSFS:-/sys}

# 파일을 읽지 못하면 missing을 냅니다.
rd() {
  cat "$1" 2>/dev/null || echo missing
}

ver=$(rd "$SYSFS/module/ha/version")
set -- "$SYSFS"/class/ha/ha[0-9]*
# 카드가 하나도 없으면 패턴이 그대로 남으므로 지웁니다.
[ -e "$1" ] || shift

rc=0
warn=0
for d in "$@"; do
  health=$(rd "$d/health")
  fw=$(rd "$d/fw_version")
  bdf=$(cd -P "$d/device" 2>/dev/null && pwd -P) || bdf=unknown
  case $health in
    ok) res=OK ;;
    degraded) res=$on_degraded ;;
    *) res=FAIL ;;
  esac
  # health는 펌웨어 준비 여부를 보지 않으므로 fw_version도 확인합니다.
  case $fw in
    [0-9]*.[0-9]*.[0-9]*) ;;
    *) res=FAIL ;;
  esac
  case $res in
    WARN) warn=1 ;;
    FAIL) rc=1 ;;
  esac
  printf '%s %s bdf=%s health=%s fw_version=%s devcmd_timeouts=%s devcmd_fw_errors=%s hdma_timeouts=%s\n' \
    "${d##*/}" "$res" "${bdf##*/}" "$health" "$fw" \
    "$(rd "$d/devcmd_timeouts")" "$(rd "$d/devcmd_fw_errors")" "$(rd "$d/hdma_timeouts")"
done

if [ "$ver" = missing ] || [ $# -lt "$expect" ]; then
  rc=2
fi
res=OK
[ "$warn" -eq 0 ] || res=WARN
[ "$rc" -eq 0 ] || res=FAIL
printf 'host %s driver=%s cards=%s expected=%s\n' "$res" "$ver" "$#" "$expect"
exit "$rc"
옵션, 환경 변수 뜻
-n N 있어야 하는 카드 수입니다. 1–8이고 기본값은 1입니다. 찾은 카드가 N장보다 적으면 종료 코드 2로 끝납니다
-s degraded인 카드도 FAIL로 판정합니다
SYSFS sysfs 경로입니다. 기본값은 /sys이며, 호스트의 /sys를 다른 경로에 마운트한 환경(예: 컨테이너)에서 지정합니다

-n에는 호스트에 꽂은 카드 수를 고정값으로 적습니다. PCI 버스에 보이는 카드 수는 lspci -D -d 20fb: | wc -l로 확인할 수 있지만, 이 값을 실행할 때마다 계산해 쓰지는 마십시오. 카드가 PCI 버스에서 사라지면 그 수도 함께 줄어 빠진 카드를 놓칩니다. 드라이버는 한 호스트에서 카드를 8장까지 인식합니다.

종료 코드 뜻
0 드라이버가 적재되어 있고, 카드가 N장 이상이며, FAIL인 카드가 없습니다. WARN인 카드는 있을 수 있습니다
1 FAIL인 카드가 있습니다
2 드라이버가 적재되지 않았거나 카드가 N장보다 적습니다. 1보다 우선합니다
3 옵션이 잘못되었습니다

실행해서 확인하기

스크립트를 설치하고 일반 사용자로 실행합니다. 카드가 2장인 호스트의 예입니다.

1
2
sudo install -m 0755 ha-healthcheck.sh /usr/local/bin/ha-healthcheck.sh
ha-healthcheck.sh -n 2; echo "exit=$?"
1
2
3
4
ha0 OK bdf=0000:17:00.0 health=ok fw_version=1.0.5 devcmd_timeouts=0 devcmd_fw_errors=0 hdma_timeouts=0
ha1 OK bdf=0000:65:00.0 health=ok fw_version=1.0.5 devcmd_timeouts=0 devcmd_fw_errors=0 hdma_timeouts=0
host OK driver=2.6.0 cards=2 expected=2
exit=0

마지막 줄이 host OK이고 종료 코드가 0이면 정상입니다. 출력은 다음과 같이 읽습니다.

  • 카드 줄은 카드 이름, 판정(OK, WARN, FAIL), 그리고 이름=값 형식의 PCI 주소(bdf)와 읽은 값입니다. 오류 카운터는 판정에 쓰지 않고 기록용으로 넣었습니다. 실행마다 남겨 두면 카운터가 언제 늘었는지 나중에 찾을 수 있습니다.
  • host 줄은 전체 판정과 드라이버 버전, 찾은 카드 수, 기대한 카드 수입니다. 전체 판정은 종료 코드가 0이 아니면 FAIL, 0이면서 WARN인 카드가 있으면 WARN, 그 밖에는 OK입니다. 드라이버가 적재되지 않았으면 driver=missing입니다.
  • 읽지 못한 파일은 missing으로 표시하고, health나 fw_version이 missing인 카드는 FAIL입니다. 드라이버가 카드를 인식하거나 제거하는 도중이거나, 텔레메트리 노드를 만들지 못한 경우입니다(커널 로그의 telemetry sysfs unavailable).
  • 카드 번호 haN은 카드의 신원이 아닙니다(카드 번호). 경보와 기록에서 카드를 가리킬 때는 bdf를 쓰십시오.
  • bdf는 hyperaccel-smi의 Bus-Id와 같습니다. health가 ok, degraded, faulted이면 Health 칸에 같은 값이 대문자로 나옵니다.

실패 경로는 카드를 건드리지 않고 시험합니다. SYSFS를 없는 경로로 주면 드라이버가 적재되지 않은 것과 같은 결과가 나옵니다.

1
SYSFS=/nonexistent ha-healthcheck.sh; echo "exit=$?"
1
2
host FAIL driver=missing cards=0 expected=1
exit=2

정상이 아닌 줄이 나오면 다음을 보십시오.

출력 종료 코드 볼 곳
haN WARN ... health=degraded 0 health가 degraded
haN FAIL ... health=faulted 1 health가 faulted
haN FAIL ... fw_version=unknown 1 fw_version이 unknown
haN FAIL ... health=missing 1 잠시 뒤 다시 실행합니다. 계속되면 텔레메트리가 unknown
host FAIL ... cards=1 expected=2 2 /dev/haN이 없음
host FAIL driver=missing 2 모듈이 적재되지 않음

FAIL인 카드를 리셋하기 전에 문제 상황의 진단 정보 모으기로 진단 정보를 먼저 저장하고, 그다음 응답하지 않는 카드 복구하기를 따르십시오. 리셋하면 원인을 보여 주는 상태가 사라집니다.

모듈을 다시 적재하거나 ha-hotreset으로 카드를 다시 인식시키는 동안에는 카드 디렉터리가 잠시 사라지거나 그 안의 노드가 아직 만들어지지 않아 종료 코드 1이나 2가 나올 수 있습니다. 이런 작업을 하는 동안에는 아래 타이머를 멈추거나 경보를 보류하십시오.


systemd 타이머로 주기 실행하기

서비스 유닛 /etc/systemd/system/ha-healthcheck.service를 만듭니다. -n에는 이 호스트의 카드 수를 적습니다.

1
2
3
4
5
6
7
8
[Unit]
Description=HyperAccel LPU health check

[Service]
Type=oneshot
ExecStart=/usr/local/bin/ha-healthcheck.sh -n 2
# 읽기만 하므로 root가 아닌 임시 사용자로 실행합니다.
DynamicUser=yes

타이머 유닛 /etc/systemd/system/ha-healthcheck.timer를 만듭니다. 부팅 5분 뒤부터 5분마다 실행합니다.

1
2
3
4
5
6
7
8
9
[Unit]
Description=Run HyperAccel LPU health check every 5 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target
1
2
sudo systemctl daemon-reload
sudo systemctl enable --now ha-healthcheck.timer

스크립트의 출력은 실행할 때마다 저널에 남고, 종료 코드가 0이 아니면 systemd가 서비스를 실패(failed)로 기록합니다. 마지막 실행 결과는 systemctl status ha-healthcheck.service로 봅니다.

1
2
sudo journalctl -u ha-healthcheck.service --since today
sudo journalctl -u ha-healthcheck.service --since today | grep -E ' (WARN|FAIL) '

실패를 알림으로 보내려면 서비스 유닛의 [Unit]에 OnFailure=로 알림을 보내는 유닛을 지정합니다. 정비하는 동안에는 sudo systemctl stop ha-healthcheck.timer로 타이머를 멈추고, 끝나면 sudo systemctl start ha-healthcheck.timer로 다시 시작합니다.


모니터링 에이전트에 연결하기

명령을 실행해 종료 코드로 상태를 판정하는 모니터링 에이전트가 있다면 같은 명령을 검사 항목으로 등록합니다.

  • 종료 코드 0만 정상으로 봅니다. 1은 카드 상태, 2는 드라이버 적재나 카드 인식, 3은 검사 설정의 문제입니다.
  • Nagios 플러그인 규약(0 정상, 1 경고, 2 위험, 3 알 수 없음)으로 종료 코드를 해석하는 에이전트에서는 FAIL인 카드(1)가 경고로만 표시됩니다. 1도 위험으로 다루도록 에이전트의 규칙을 정하십시오.
  • 출력의 WARN, FAIL 줄을 경보 본문에 넣으면 어느 카드가 왜 실패했는지 함께 전달됩니다.
  • 에이전트가 컨테이너에서 돌고 호스트의 /sys를 다른 경로(예: /host/sys)에 마운트했다면 SYSFS=/host/sys로 그 경로를 알려 줍니다.

카드가 보이는지만 확인하면 될 때는 hyperaccel-smi의 종료 코드로도 충분합니다. 보이는 카드가 없으면 2, 하나 이상이면 0으로 끝납니다. 카드 상태는 보지 않으므로 FAULTED인 카드가 있어도 0이고, 환경 변수 HYPERACCEL_VISIBLE_DEVICES가 설정되어 있으면 그 값이 허용하는 카드만 셉니다(all이면 모든 카드, none이나 빈 값이면 0장). ha-healthcheck.sh는 이 변수와 관계없이 호스트의 모든 카드를 봅니다.

1
hyperaccel-smi > /dev/null; echo $?

함께 보기