카드 상태 헬스체크 만들기¶
호스트의 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 | |
| 옵션, 환경 변수 | 뜻 |
|---|---|
-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 | |
1 2 3 4 | |
마지막 줄이 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 | |
1 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 | |
타이머 유닛 /etc/systemd/system/ha-healthcheck.timer를 만듭니다. 부팅 5분 뒤부터 5분마다 실행합니다.
1 2 3 4 5 6 7 8 9 | |
1 2 | |
스크립트의 출력은 실행할 때마다 저널에 남고, 종료 코드가 0이 아니면 systemd가 서비스를 실패(failed)로 기록합니다. 마지막 실행 결과는 systemctl status ha-healthcheck.service로 봅니다.
1 2 | |
실패를 알림으로 보내려면 서비스 유닛의 [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 | |
함께 보기¶
- 텔레메트리 —
health판정,unknown의 뜻, 경보 기준 - sysfs 노드 — 스크립트가 읽는 노드의 정의
- 문제 해결 —
WARN이나FAIL이 나왔을 때 - FATAL과 복구
- hang 감지와 워치독 — 헬스체크가 보지 않는 진행 중인 정체
- hyperaccel-smi
- Prometheus로 텔레메트리 수집하기
- 문제 상황의 진단 정보 모으기 —
FAIL이 나왔을 때 리셋 전에 할 일 - 응답하지 않는 카드 복구하기