콘텐츠로 이동

Prometheus로 텔레메트리 수집하기

Prometheus와 node_exporter로 서버를 모니터링하는 운영자를 위한 튜토리얼입니다. 끝까지 따라 하면 node_exporter 하나로 카드마다 온도·전압·전류·전력과 health, 메모리 사용량, 작업 수, 오류 카운터, 사용률을 수집하고, 카드 이름으로 값을 묶어 보고, 기본 경보 규칙을 걸 수 있습니다. 드라이버 설정은 바꾸지 않습니다. 노드마다의 뜻과 unknown이 나오는 조건은 텔레메트리에 있습니다.


시작하기 전에

온도·전압·전류·전력은 node_exporter의 hwmon 수집기가 설정 없이 가져가고(1단계), 나머지 값은 이 장의 스크립트가 /sys/class/ha/haN/에서 읽어 파일로 쓰면 node_exporter의 textfile 수집기가 읽습니다(2단계). 필요한 것은 다음과 같습니다.

  • 드라이버가 카드를 인식한 호스트. 설치 확인을 보십시오.
  • 호스트에서 실행 중인 node_exporter. 이 장은 기본 포트 9100을 씁니다. hwmon 수집기와 textfile 수집기는 기본으로 켜져 있지만, textfile 수집기는 --collector.textfile.directory로 디렉터리를 지정해야 그 안의 *.prom 파일을 읽습니다. 이 장은 /var/lib/node_exporter/textfile_collector를 예로 씁니다.

1. hwmon 값을 확인합니다

커널이 hwmon을 지원하면 드라이버는 카드마다 name이 ha인 hwmon 디바이스를 등록합니다. 먼저 hwmon 디바이스가 있는지 확인합니다.

1
grep -l '^ha$' /sys/class/hwmon/hwmon*/name

카드 수만큼 경로가 나와야 합니다. 하나도 나오지 않으면 hwmon 연동을 보십시오. 이때는 온도·전압·전류·전력이 수집되지 않지만, 2단계부터는 그대로 진행할 수 있습니다.

node_exporter는 LPU의 hwmon 값을 다음 메트릭으로 내고, 값을 기본 단위로 바꿉니다.

hwmon 파일 메트릭 sensor 라벨 단위
temp1_input–temp15_input node_hwmon_temp_celsius temp1–temp15 °C
in0_input–in3_input node_hwmon_in_volts in0–in3 V
curr1_input–curr4_input node_hwmon_curr_amps curr1–curr4 A
power1_input node_hwmon_power_watt power1 W
  • 채널마다의 이름(peak, avg, top_core, total 등)은 node_hwmon_sensor_label의 label 라벨에 있습니다. 최고 온도는 temp1(peak), rail 전력 합은 power1(total)입니다. 전체 대응은 sysfs 노드를 보십시오.
  • 카드는 chip 라벨로 구별합니다. node_exporter는 hwmon 디바이스가 붙은 PCI 디바이스의 sysfs 경로에서 chip을 만듭니다. LPU의 chip은 node_hwmon_chip_names에서 chip_name="ha"인 줄로 찾습니다(4단계에서 확인합니다).
  • 드라이버가 값을 믿을 수 없으면 hwmon 파일은 읽기 오류를 내고, node_exporter는 그 센서를 그 수집에서 뺍니다. 값이 0으로 떨어지지 않고 그 구간의 샘플이 비어 보입니다.

2. textfile 스크립트를 설치합니다

hwmon에 없는 값은 아래 스크립트가 내보냅니다. 스크립트는 /sys/class/ha/haN/의 노드를 읽어 textfile 수집기 형식의 ha.prom 파일을 씁니다. POSIX sh로 작성해 bash가 없는 호스트에서도 실행됩니다.

메트릭 형식 원본 값
ha_cards gauge /sys/class/ha/haN 카드 수. 모듈이 적재되지 않았으면 0
ha_driver_info gauge /sys/module/ha/version 1. version 라벨에 드라이버 버전
ha_card_info gauge fw_version, serial, device 링크 1. chip, fw_version, serial 라벨
ha_health gauge health state 라벨(ok, degraded, faulted, unknown)마다 한 줄. 지금 상태만 1
ha_dram_used_bytes, ha_dram_free_bytes gauge dram_used, dram_free 바이트
ha_inflight, ha_streams gauge inflight, stream_count 개수
ha_devcmd_timeouts_total, ha_devcmd_fw_errors_total, ha_hdma_timeouts_total counter devcmd_timeouts, devcmd_fw_errors, hdma_timeouts 횟수
ha_util_ratio gauge util ip 라벨마다 한 줄. 0–1(백분율 ÷ 100)

ha_cards와 ha_driver_info를 뺀 메트릭에는 카드 이름 card(haN)와 PCI 주소 pci 라벨이 붙습니다. haN 번호는 카드 구성이나 인식 순서에 따라 바뀔 수 있으므로, 카드를 오래 추적할 때는 pci나 ha_card_info의 serial을 쓰십시오.

 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
#!/bin/sh
# LPU 텔레메트리를 node_exporter textfile 수집기가 읽는 ha.prom 파일로 씁니다.
# 사용법: ha-prom-textfile.sh [textfile 디렉터리]
# 호스트의 /sys가 다른 경로에 마운트되어 있으면 SYSFS에 그 경로를 지정합니다.
DIR=${1:-/var/lib/node_exporter/textfile_collector}
SYSFS=${SYSFS:-/sys}
export LC_ALL=C

# 카드마다 "<공통 라벨> <카드 디렉터리>"를 한 줄씩 냅니다.
cards() {
  for d in "$SYSFS"/class/ha/ha*; do
    p=$(cd -P "$d/device" 2>/dev/null && pwd -P) || continue
    printf 'card="%s",pci="%s" %s\n' "${d##*/}" "${p##*/}" "$d"
  done
}
hdr() { printf '# HELP %s %s\n# TYPE %s %s\n' "$1" "$3" "$1" "$2"; }
# 라벨 값의 \와 "를 이스케이프합니다.
esc() { printf '%s' "$1" | sed 's/[\\"]/\\&/g'; }

# 정수 하나를 내는 노드를 메트릭 하나로 냅니다.
# unknown처럼 숫자가 아닌 값은 0으로 바꾸지 않고 샘플을 뺍니다.
num() { # 메트릭 형식 설명 노드
  hdr "$1" "$2" "$3"
  cards | while read -r l d; do
    v=$(cat "$d/$4" 2>/dev/null) || continue
    case ${v#-} in '' | *[!0-9]*) continue ;; esac
    printf '%s{%s} %s\n' "$1" "$l" "$v"
  done
}

tmp=$(mktemp "$DIR/.ha.prom.XXXXXX") || exit 1
trap 'rm -f "$tmp"' EXIT
{
  hdr ha_cards gauge 'LPU cards found under /sys/class/ha.'
  echo "ha_cards $(cards | wc -l)"

  hdr ha_driver_info gauge 'Loaded ha.ko version. Always 1.'
  v=$(cat "$SYSFS/module/ha/version" 2>/dev/null) &&
    printf 'ha_driver_info{version="%s"} 1\n' "$(esc "$v")"

  hdr ha_card_info gauge 'Card identity. Always 1.'
  cards | while read -r l d; do
    p=$(cd -P "$d/device" 2>/dev/null && pwd -P) || continue
    fw=$(cat "$d/fw_version" 2>/dev/null) || continue
    sn=$(cat "$d/serial" 2>/dev/null) || continue
    # node_exporter hwmon 수집기의 chip 라벨: PCI 경로의 마지막 두 단계, '.'은 '_'
    b=${p%/*}
    chip=$(printf '%s_%s' "${b##*/}" "${p##*/}" | tr . _)
    printf 'ha_card_info{%s,chip="%s",fw_version="%s",serial="%s"} 1\n' \
      "$l" "$chip" "$(esc "$fw")" "$(esc "$sn")"
  done

  hdr ha_health gauge 'Driver health verdict. 1 for the current state.'
  cards | while read -r l d; do
    h=$(cat "$d/health" 2>/dev/null) || continue
    for s in ok degraded faulted unknown; do
      v=0
      [ "$h" = "$s" ] && v=1
      printf 'ha_health{%s,state="%s"} %s\n' "$l" "$s" "$v"
    done
  done

  num ha_dram_used_bytes gauge 'Allocated device DRAM.' dram_used
  num ha_dram_free_bytes gauge 'Free device DRAM.' dram_free
  num ha_inflight gauge 'Accepted work not finished yet.' inflight
  num ha_streams gauge 'Streams with work left.' stream_count
  num ha_devcmd_timeouts_total counter 'Device command timeouts.' devcmd_timeouts
  num ha_devcmd_fw_errors_total counter 'Firmware error responses.' devcmd_fw_errors
  num ha_hdma_timeouts_total counter 'DMA transfer timeouts.' hdma_timeouts

  hdr ha_util_ratio gauge 'Per-IP utilization, 0 to 1.'
  cards | while read -r l d; do
    # util이 unknown이면 "<IP> <백분율>%" 줄이 없어 샘플이 나오지 않습니다.
    awk -v l="$l" '$1 ~ /^[a-z0-9_]+$/ && $2 ~ /^[0-9.]+%$/ {
      printf "ha_util_ratio{%s,ip=\"%s\"} %g\n", l, $1, $2 / 100 }' \
      "$d/util" 2>/dev/null
  done
} >"$tmp"
chmod 0644 "$tmp" && mv -f "$tmp" "$DIR/ha.prom"

스크립트를 설치하고 한 번 실행해 봅니다.

1
2
3
4
sudo install -m 0755 ha-prom-textfile.sh /usr/local/bin/ha-prom-textfile.sh
sudo install -d -m 0755 /var/lib/node_exporter/textfile_collector
sudo /usr/local/bin/ha-prom-textfile.sh /var/lib/node_exporter/textfile_collector
cat /var/lib/node_exporter/textfile_collector/ha.prom

스크립트는 다음 규칙을 따릅니다.

  • 모르는 값을 0으로 바꾸지 않습니다. 숫자를 내는 노드가 unknown처럼 숫자가 아닌 값을 내면 그 카드의 그 메트릭을 이번 파일에서 뺍니다. 0을 쓰면 "값을 모른다"가 "값이 0이다"로 바뀌어 그래프와 경보가 틀어지기 때문입니다. util이 unknown이면 그 카드의 ha_util_ratio가 모두 빠집니다. 문자열 값은 그대로 옮기므로 health가 unknown이면 state="unknown"이 1이 되고, 펌웨어가 준비되기 전에는 fw_version="unknown"으로 보입니다.
  • 주기 수집에 맞는 노드만 읽습니다. 읽는 노드는 모두 드라이버가 유지하는 값을 냅니다. 예외는 fw_version과 serial입니다. fw_version이 unknown인 동안에는 두 노드를 읽을 때 드라이버가 펌웨어 준비 여부를 다시 확인합니다(수집 주기와 비용). fw_update_progress는 노드를 읽을 때마다 드라이버가 디바이스에서 직접 읽어 오므로 읽지 않고, help(설명 텍스트)와 bypass_range_check(디버그 설정)도 수집할 값이 아니므로 읽지 않습니다.
  • 카드가 없어도 파일을 씁니다. 모듈이 적재되지 않았거나 카드가 없으면 카드별 샘플 없이 ha_cards 0을 씁니다. 사라진 카드의 이전 값이 남아 보이지 않게 하기 위해서입니다.
  • 파일을 한 번에 바꿉니다. 같은 디렉터리에 임시 파일을 다 쓴 뒤 mv로 바꾸므로 node_exporter가 쓰다 만 파일을 읽지 않습니다. 임시 파일 이름은 .prom으로 끝나지 않아 수집 대상이 아닙니다.
  • sysfs 경로를 바꿀 수 있습니다. 호스트의 /sys가 다른 경로에 마운트되어 있으면(예: 컨테이너 안의 /host/sys) 환경 변수 SYSFS에 그 경로를 지정합니다.

정수 하나를 내는 노드는 num 줄을 하나 더해 내보낼 수 있습니다. 예를 들어 hwmon이 없는 커널에서는 num ha_temp_celsius gauge 'Peak on-die temperature.' temp를 더하면 최고 온도(°C)를 수집합니다.


3. 주기적으로 실행합니다

systemd 타이머로 15초마다 실행합니다. 서비스 유닛과 타이머 유닛을 만듭니다.

1
2
3
4
5
6
7
# /etc/systemd/system/ha-prom-textfile.service
[Unit]
Description=Write LPU telemetry for the node_exporter textfile collector

[Service]
Type=oneshot
ExecStart=/usr/local/bin/ha-prom-textfile.sh /var/lib/node_exporter/textfile_collector
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# /etc/systemd/system/ha-prom-textfile.timer
[Unit]
Description=Run ha-prom-textfile.service every 15 seconds

[Timer]
OnBootSec=30s
OnUnitActiveSec=15s
AccuracySec=1s

[Install]
WantedBy=timers.target
1
2
3
sudo systemctl daemon-reload
sudo systemctl enable --now ha-prom-textfile.timer
systemctl list-timers ha-prom-textfile.timer
  • AccuracySec을 지정하지 않으면 기본값 1분이 적용되어, systemd가 실행 시각을 최대 1분까지 늦출 수 있습니다.
  • Prometheus가 가져가는 값은 마지막으로 쓴 파일의 값이므로 타이머 주기만큼 늦을 수 있습니다. 주기는 Prometheus의 수집 주기에 맞추십시오.
  • 서비스는 root로 실행됩니다. textfile 디렉터리에 쓸 수 있는 사용자라면 [Service]에 User=를 지정해 그 사용자로 실행해도 됩니다.

4. 수집을 확인합니다

node_exporter가 파일과 hwmon 값을 읽었는지 확인합니다.

1
2
curl -s http://localhost:9100/metrics |
  grep -E '^(ha_cards|ha_card_info|ha_health|node_textfile_scrape_error)|chip_name="ha"'

카드가 한 장인 호스트의 출력 예입니다. node_exporter는 라벨을 이름 순서로 정렬해 냅니다.

1
2
3
4
5
6
7
8
ha_card_info{card="ha0",chip="0000:00:01_0_0000:01:00_0",fw_version="1.0.5",pci="0000:01:00.0",serial="HA-1a2b3c4d-5e6f-7a8b-9c0d-1e2f00000000"} 1
ha_cards 1
ha_health{card="ha0",pci="0000:01:00.0",state="degraded"} 0
ha_health{card="ha0",pci="0000:01:00.0",state="faulted"} 0
ha_health{card="ha0",pci="0000:01:00.0",state="ok"} 1
ha_health{card="ha0",pci="0000:01:00.0",state="unknown"} 0
node_hwmon_chip_names{chip="0000:00:01_0_0000:01:00_0",chip_name="ha"} 1
node_textfile_scrape_error 0
  • ha_ 메트릭이 하나도 없으면 node_exporter의 --collector.textfile.directory가 스크립트에 지정한 디렉터리와 같은지 확인하십시오.
  • node_textfile_scrape_error가 1이면 node_exporter가 textfile 디렉터리나 그 안의 .prom 파일을 읽지 못한 것입니다. 원인은 node_exporter 로그에 남습니다.
  • ha_card_info의 chip 값은 node_hwmon_chip_names의 chip 값과 같아야 합니다. 다음 절의 결합은 이 값을 기준으로 이루어집니다. node_hwmon_chip_names 줄이 없으면 1단계를 보십시오.

카드 이름으로 hwmon 값 보기

hwmon 메트릭에는 카드 이름이 없습니다. ha_card_info와 chip으로 결합하면 card와 pci 라벨을 붙일 수 있습니다. 다음은 카드별 최고 온도를 구하는 PromQL입니다.

1
2
node_hwmon_temp_celsius{sensor="temp1"}
  * on (instance, chip) group_left (card, pci) ha_card_info

ha_card_info의 값은 항상 1이므로 결과는 온도 그대로입니다. 같은 구성의 서버끼리는 chip 값이 같을 수 있으므로 instance도 함께 맞춥니다. 전압, 전류, 전력은 메트릭 이름과 sensor 조건을 바꿔 같은 식을 씁니다.


경보 규칙 예

경보 기준의 권장 사항을 Prometheus 경보 규칙으로 옮긴 예입니다. 규칙 파일(예: ha-lpu.rules.yml)로 저장하고 promtool check rules ha-lpu.rules.yml로 문법을 확인한 뒤, Prometheus 설정의 rule_files에 추가하십시오.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
groups:
  - name: hyperaccel-lpu
    rules:
      - alert: LpuFaulted
        expr: ha_health{state="faulted"} == 1
      - alert: LpuErrorCountersIncreased
        expr: |
          increase(ha_devcmd_timeouts_total[10m]) > 0
          or increase(ha_devcmd_fw_errors_total[10m]) > 0
          or increase(ha_hdma_timeouts_total[10m]) > 0
      - alert: LpuUtilUnknown
        expr: ha_card_info unless on (instance, card) ha_util_ratio
        for: 5m
      - alert: LpuCardMissing
        # 4를 이 호스트에 장착한 카드 수로 바꾸십시오.
        expr: ha_cards < 4
        for: 5m
      - alert: LpuTextfileStale
        expr: |
          time() - node_textfile_mtime_seconds{file=~".*/ha.prom"} > 120
          or node_textfile_scrape_error == 1
경보 뜻과 대응
LpuFaulted 카드가 FATAL이거나 마지막 리셋이 실패했습니다. 리셋하기 전에 문제 상황의 진단 정보 모으기로 진단 정보를 저장하고 응답하지 않는 카드 복구하기를 따르십시오
LpuErrorCountersIncreased 최근 10분 안에 시간 초과나 펌웨어 오류가 새로 생겼습니다. last_hang과 커널 로그를 확인하십시오. 카운터는 드라이버가 카드를 다시 인식하면 0부터 다시 세므로 경보는 값이 아니라 증가분으로 겁니다
LpuUtilUnknown util이 5분 넘게 unknown입니다. 원인은 폴러가 멈췄거나 FATAL이 이어지는 경우 등입니다(unknown이 나오는 조건)
LpuCardMissing 보이는 카드가 기대한 수보다 적습니다. 모듈이 적재되지 않았거나, 드라이버가 일부 카드를 인식하지 못했거나, 카드가 PCI 버스에서 사라졌습니다. 모듈을 다시 적재하거나 ha-hotreset을 실행하는 동안에도 잠시 줄어듭니다
LpuTextfileStale ha.prom이 2분 넘게 갱신되지 않았거나 node_exporter가 textfile을 읽지 못했습니다. 타이머가 멈춰도 node_exporter는 마지막 파일을 계속 내보내므로, 이 경보로 오래된 값을 가려냅니다

degraded에는 경보를 걸지 마십시오

degraded는 오류가 한 번이라도 있었으면 드라이버가 카드를 다시 인식할 때까지 유지됩니다. 문제가 계속되는지는 LpuErrorCountersIncreased처럼 카운터 증가로 판단하고, degraded는 대시보드의 상태 표시에 쓰십시오.


함께 보기