> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 監視のトラブルシューティング

インストールは完了したのにデータが得られない場合や、デバイスがメトリクスを報告しなくなった場合は、本ページの手順に沿って切り分けを進めてください。

## 症状別の参照先

| 症状 | セクション |
| :- | :- |
| 正しくインストールしたのにメトリクスがまったく返らない | [Prometheus にも Grafana にもデータが表示されない](#prometheus-にも-grafana-にもデータが表示されない) |
| 特定のデバイスで `pdu_up 0` または `xrdu_up 0` になる | [デバイスへの到達性](#デバイスへの到達性) |
| XRDU の一部のセンサーは報告されるが、ほかは報告されない | [XRDU のプローブ失敗](#xrdu-のプローブ失敗) |
| PDU と XRDU は動作しているのに RDU のメトリクスがない | [SambaNova エクスポーターがメトリクスを報告しない](#sambanova-エクスポーターがメトリクスを報告しない) |
| ダッシュボードが存在しない、または空になっている | [ダッシュボードが空の場合](#ダッシュボードが空の場合) |
| ラックの電力値が約 3 倍大きく表示される | `level="total"` でフィルタリングします。[PDU エクスポーターのラベル](https://docs.sambanova.ai/docs/ja/v2.2.6/sambastack/hardware-admin/sambarack-manager/monitoring/exporter-pdu.md#ラベル) をご参照ください。 |
| Pod が起動しない | [Pod とイメージ](#pod-とイメージ) |

## Prometheus にも Grafana にもデータが表示されない

以下を順に確認します。ほとんどのケースは最初の 2 つが原因です。

### 1. プローブが作成されていない

```bash theme={}
kubectl -n monitoring get probe,servicemonitor
```

`<exporter>.enabled` はエクスポーターをデプロイする設定で、`<exporter>.probe.enabled` は Prometheus にデバイスをスクレイプさせる設定です。前者だけでは、エクスポーターは稼働しても何も生成しません。Helm が実際に適用した値を確認します。

```bash theme={}
helm -n monitoring get values hwmon
```

### 2. Prometheus がプローブを選択していない

正しくインストールしたのにデータが得られない原因として最も多いのがこれです。Prometheus が選択条件とするラベルを持たない `Probe` や `ServiceMonitor` は、作成自体は成功するものの、その後一度もスクレイプされません — しかもエラーはどこにも出ません。

```bash theme={}
kubectl get prometheus -A -o jsonpath='{.items[*].spec.probeSelector}'; echo
kubectl get prometheus -A -o jsonpath='{.items[*].spec.serviceMonitorSelector}'; echo

kubectl -n monitoring get probe -o jsonpath='{.items[*].metadata.labels}'; echo
```

両者のラベルが一致している必要があります。`kube-prometheus-stack` は `release: <its-release-name>` を選択条件とします。空のセレクター (`{}`) はすべてを選択します。values ファイルで `probe.labels` と `serviceMonitor.labels` を設定してアップグレードすることで修正できます。

### 3. ターゲットがダウンしている

Prometheus の UI を開き、**Status**、**Targets** の順に移動します。有効化した各 `Probe` はジョブとして表示され、デバイスごとに 1 つのターゲットを持ちます。down と表示されているターゲットには、スクレイプエラーの内容が表示されます。

ターゲットがそもそも表示されない場合は、Prometheus がプローブを選択していません。ステップ 2 に戻ってください。

## デバイスへの到達性

エクスポーターの Pod が PDU や BMC に到達できるのは、その Pod が動作するノードが管理ネットワークへの経路を持つ場合のみです。通常、ノードはフロントエンド側と管理ネットワーク側の両方のアドレスを持ちますが、常にそうとは限りません。経路がないノードでは、チャートをどう設定してもメトリクスは得られません。

以下の確認は、ワークステーションからではなく、**クラスターのノード上で**実行してください。各ループには実際のデバイスアドレスを列挙します。2 つ目のループは XRDU の BMC パスワードの入力を求める形式のため、パスワードがシェル履歴に残りません。

```bash theme={}
for ip in <pdu-1-ip> <pdu-2-ip>; do
  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 \
    "http://$ip/api/sys" 2>/dev/null)
  echo "PDU  $ip -> http=${code:-none} curl_exit=$?"
done
```

```bash theme={}
read -rs -p "XRDU BMC password: " XRDU_PASSWORD; echo

for ip in <xrdu-0-ip> <xrdu-1-ip>; do
  code=$(curl -sk -o /dev/null -w '%{http_code}' --max-time 10 \
    -u "root:$XRDU_PASSWORD" \
    "https://$ip/xyz/openbmc_project/sensors/enumerate" 2>/dev/null)
  echo "XRDU $ip -> http=${code:-none} curl_exit=$?"
done

unset XRDU_PASSWORD
```

| 結果 | 意味 | 対処方法 |
| :- | :- | :- |
| `http=200` | ノードからデバイスに到達できています。これらのデバイスでは、応答に 2 秒以上かかるのは正常です。 | — |
| `http=401` | XRDU のパスワードが誤っている | [XRDU パスワードの更新](#xrdu-パスワードの更新) をご参照ください |
| `http=000` かつ `curl_exit` が 0 以外 | 経路がありません。クラスターが違うか、ノードが管理ネットワーク上のインターフェースを持っていません。 | 管理ネットワークに接続されたノードに、`nodeSelector` でエクスポーターの Pod を固定してください |

XRDU には `-k` と `-u` の両方が必須です。BMC は自己署名証明書を使用し、認証を必須とするため、オプションなしの `curl https://...` は証明書エラーで失敗し、あたかもデバイスがダウンしているかのように見えます。

経路を持つノードと持たないノードが混在する場合は、エクスポーターをノードに固定します。

```yaml theme={}
pdu-exporter:
  nodeSelector:
    <label-that-marks-management-network-nodes>: "true"
xrdu-exporter:
  nodeSelector:
    <label-that-marks-management-network-nodes>: "true"
```

> [!NOTE]
>
> 到達できないデバイスに対しては、エラーステータスではなく、HTTP 200 と `pdu_up 0` または `xrdu_up 0` が返ります。これは意図的な設計です。200 以外の応答を返すと Prometheus がそのスクレイプ全体を破棄し、停止検知のアラートが依存する `up` サンプルまで失われるためです。

## XRDU のプローブ失敗

XRDU の場合、`xrdu_up 0` は、認証情報の拒否・証明書の問題・デバイスに到達できない場合のいずれでも同じように記録されます。これらはログで区別できます。

```bash theme={}
kubectl -n monitoring logs deploy/xrdu-exporter | grep 'probe failed'
```

| ログまたは症状 | 原因 | 対処方法 |
| :- | :- | :- |
| `x509: negative serial number` | エクスポーターのイメージが古い | チャートのデフォルトイメージ (1.0.0) を使用してください |
| `401 Unauthorized` | パスワードが誤っている | [XRDU パスワードの更新](#xrdu-パスワードの更新) をご参照ください |
| `dial tcp ... i/o timeout` | ノードから BMC ネットワークへの経路がない | [デバイスへの到達性](#デバイスへの到達性) をご参照ください |
| `response was not the JSON envelope` | そのアドレスにあるのは XRDU の BMC ではない | `snctl rack show` の結果とアドレスを突き合わせてください |
| Pod の `CreateContainerConfigError` | Secret に `XRDU_PASSWORD` キーがない | 正しいキー名で Secret を作り直してください。[XRDU パスワードの更新](#xrdu-パスワードの更新) をご参照ください。 |

### XRDU パスワードの更新

エクスポーターが Secret からパスワードを読み取るのは、Pod の起動時のみです。Secret を変更したら、エクスポーターを再起動してください。

SambaRack Manager がインストールされているホストで、現在のパスワードを取得します。

```bash theme={}
snctl secret get --device-type xrdu --show-value
```

次に、`kubectl` にアクセスできるホストで Secret を置き換え、エクスポーターを再起動します。

```bash theme={}
read -rs -p "XRDU BMC password: " XRDU_PASSWORD; echo

kubectl -n monitoring create secret generic xrdu-creds \
  --from-literal=XRDU_USERNAME=root \
  --from-literal=XRDU_PASSWORD="$XRDU_PASSWORD" \
  --dry-run=client -o yaml | kubectl apply -f -

unset XRDU_PASSWORD

kubectl -n monitoring rollout restart deploy/xrdu-exporter
```

## SambaNova エクスポーターがメトリクスを報告しない

このエクスポーターはホスト上のプロセスです。チャートはこのエクスポーターをデプロイせず、起動させることもできません。

```bash theme={}
kubectl -n monitoring get pods -l app=sambanova-exporter -o wide
kubectl -n monitoring get endpoints sambanova-exporter -o yaml | grep -E 'addresses|notReady'
```

Pod が Running のまま Ready にならない場合や、エンドポイントが `notReadyAddresses` に入っている場合は、そのノードでホスト側のサービスが停止しています。Readiness Probe は意図的にホストプロセスの状態に追随するようになっており、停止したエクスポーターはゼロ値を報告するのではなく、Service から外れます。

該当するホストモジュール上で実行します。

```bash theme={}
systemctl is-active sambanova_exporter
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9101/metrics
```

| 結果 | 原因 | 対処方法 |
| :- | :- | :- |
| `inactive` かつ `000` | サービスが無効化されている (新規システムの出荷時の状態) | `systemctl enable --now sambanova_exporter` |
| パッケージが見つからない | このホストに SambaNova Runtime がインストールされていない | SambaNova Runtime 1.26.3-1 以降をインストールしてから、`yum install -y sambanova-runtime-exporter` を実行してください |
| `active` だが、そのノードでエクスポーターの Pod が動いていない | チャートは `snRduArch` ラベルを持つノードにのみ Pod をスケジュールする | ノードに `snRduArch` ラベルが付いているか確認してください |
| サービスが起動に失敗する | 設定ファイルは存在するが、読み取りまたは解析ができない | `systemctl status sambanova_exporter` を確認してください。ファイルが存在しない場合は無視されますが、解析できないファイルは致命的なエラーになります。 |

## ダッシュボードが空の場合

以下を順に確認します。

1. **エクスポーターが有効化されていないか、`probe.enabled` がオフになっている**。[Prometheus にも Grafana にもデータが表示されない](#prometheus-にも-grafana-にもデータが表示されない) をご参照ください。
2. **Prometheus がターゲットをスクレイプしていない**。**Status**、**Targets** の順に開いて確認します。
3. **パネルが必要とするラベルが設定されていない**。ラックごとの電力表示には各 PDU ターゲットの `rack` ラベルが、RDU ダッシュボードには `sambanova-exporter.serviceMonitor.rackMap` が必要です。[ダッシュボードのカスタマイズ](https://docs.sambanova.ai/docs/ja/v2.2.6/sambastack/hardware-admin/sambarack-manager/monitoring/monitoring-reference-dashboards.md#ダッシュボードのカスタマイズ) をご参照ください。
4. **ダッシュボードがそもそも表示されない**。サイドカーのラベルが一致していません。[Helm チャートでのインストール](https://docs.sambanova.ai/docs/ja/v2.2.6/sambastack/hardware-admin/sambarack-manager/monitoring/monitoring-reference-dashboards.md#helm-チャートでのインストール) をご参照のうえ、Grafana で `sambarack` を検索してください — デフォルトの `kube-prometheus-stack` では、ダッシュボードは General フォルダーに配置されます。

## Pod とイメージ

| 症状 | 原因 | 対処方法 |
| :- | :- | :- |
| `ImagePullBackOff` | プルシークレットがないか、有効期限の短いアクセストークンから作成されている | `_json_key` 形式とキーファイルを使って作り直してください。[プルシークレットの作成](https://docs.sambanova.ai/docs/ja/v2.2.6/sambastack/hardware-admin/sambarack-manager/monitoring/monitoring-install.md#プルシークレットの作成) をご参照ください。 |
| `exec format error`、Pod がクラッシュループする | Apple シリコンのワークステーションで arm64 イメージを取得し、amd64 クラスターにプッシュした | インストールガイドの `crane pull` コマンドと同様に、`crane pull --platform linux/amd64` で取得し直してください |
| `helm install` が認識できない kind のエラーで失敗する | `probe.enabled` がオンなのに prometheus-operator の CRD がない | `kube-prometheus-stack` をインストールするか、プローブ関連のスイッチをオフのままにしてください |
| 他はすべて正常に見えるのに、Prometheus の Pod が `ImagePullBackOff` のまま | `prometheus-config-reloader` がエアギャップを越えて持ち込まれていない。オペレーターが実行時にサイドカーとして注入するため、レンダリングされたマニフェストの `image:` には現れません。 | 使用している prometheus-operator のバージョンに対応する `prometheus-config-reloader` イメージを持ち込んでください |
| オペレーターの Pod が `MountVolume.SetUp failed for volume "tls-secret"` で `ContainerCreating` のまま | アドミッション Webhook を無効化しているのに `prometheusOperator.tls.enabled` が true のまま | `prometheusOperator.tls.enabled: false` を設定してください |
| ログインに成功した後、レジストリから `401 unauthorized` が返る | その後に `gcloud auth login` を実行したため、ユーザーアカウントがアクティブになっている | `gcloud auth activate-service-account --key-file=<path-to-service-account-key>` を再実行してください |

## SambaNova に提出する診断情報の収集

```bash theme={}
kubectl -n monitoring get pods,svc,probe,servicemonitor -o wide
helm -n monitoring get values hwmon
kubectl -n monitoring logs deploy/pdu-exporter  --tail=200
kubectl -n monitoring logs deploy/xrdu-exporter --tail=200
kubectl get prometheus -A -o jsonpath='{.items[*].spec.probeSelector}'
helm -n monitoring list
```

メトリクスを報告していない各ホストモジュール上で実行します。

```bash theme={}
systemctl status sambanova_exporter
journalctl -u sambanova_exporter --since "1 hour ago"
```

チャートのバージョン、エクスポーターのイメージタグ、インストールが接続環境かエアギャップ環境かの別も添えてください。共有する前に、デバイスの認証情報をマスクしてください。

## 次のステップ

* [監視のインストール](https://docs.sambanova.ai/docs/ja/v2.2.6/sambastack/hardware-admin/sambarack-manager/monitoring/monitoring-install.md)
* [監視の概要](https://docs.sambanova.ai/docs/ja/v2.2.6/sambastack/hardware-admin/sambarack-manager/monitoring/monitoring-overview.md)