From 5254befb923666988b545240fa8b07831062184b Mon Sep 17 00:00:00 2001 From: openclaw Date: Wed, 25 Feb 2026 16:06:21 +0000 Subject: [PATCH] docs(metrics): re-verify openclaw_* metrics after PR #7123 OTel dependency fix - Refs: T-20260225-009 - Co-Authored-By: Claude Opus 4.6 --- .../T-20260225-009-reverify-metrics/plan.md | 33 +++ .../metrics-verification.md | 260 +++++++++++++++++- 2 files changed, 291 insertions(+), 2 deletions(-) create mode 100644 docs/project_docs/T-20260225-009-reverify-metrics/plan.md diff --git a/docs/project_docs/T-20260225-009-reverify-metrics/plan.md b/docs/project_docs/T-20260225-009-reverify-metrics/plan.md new file mode 100644 index 000000000..227f5bed2 --- /dev/null +++ b/docs/project_docs/T-20260225-009-reverify-metrics/plan.md @@ -0,0 +1,33 @@ +# T-20260225-009: OpenClaw メトリクス再検証結果 + +## 概要 + +PR #7123（`boxp/arch`: OTel 依存追加）反映後に `openclaw_*` メトリクスの取得状況を再検証した。 + +## 検証結果サマリ + +| 項目 | 前回 (2026-02-21) | 今回 (2026-02-25) | 変化 | +|------|------------------|------------------|------| +| `@opentelemetry/api` エラー | 発生 | **消失** | 改善 | +| プラグインロード失敗ログ | 発生 | **消失** | 変化 | +| `openclaw_*` メトリクス | 0/18 | **0/18** | 変化なし | +| `target_info` (OTel自動生成) | なし | なし | 変化なし | + +**結論: PR #7123 により `@opentelemetry/api` のモジュール解決エラーは解消されたが、メトリクスは依然として Prometheus に到達していない（0/18）。** + +## 新たな根本原因仮説 + +1. **SDK 内部初期化失敗（最有力）**: OTel パッケージが `/opt/otel-deps/node_modules` にインストールされ `NODE_PATH` で参照可能になったが、SDK 初期化時にバージョン競合や内部エラーで静かに失敗 +2. **OTLP エクスポーター送信失敗**: OTel SDK のデフォルト動作で export エラーが swallow されている +3. **OpenClaw v2026.2.22 でのプラグインシステム変更**: `[plugins]` ログが一切なく、プラグインロード方式が変更された可能性 + +## 推奨アクション + +1. **即時**: ConfigMap に `OTEL_LOG_LEVEL=debug` を追加して OTel 内部エラーを特定 +2. **短期**: OpenClaw v2026.2.23 へアップデート（changelog 確認後） +3. **代替**: `/app/node_modules` 直接インストール方式への変更を検討 + +## 詳細 + +検証の完全な結果は以下を参照: +- `docs/project_docs/openclaw-app-metrics-dashboard/metrics-verification.md` diff --git a/docs/project_docs/openclaw-app-metrics-dashboard/metrics-verification.md b/docs/project_docs/openclaw-app-metrics-dashboard/metrics-verification.md index 19529aa38..ecd8cbd46 100644 --- a/docs/project_docs/openclaw-app-metrics-dashboard/metrics-verification.md +++ b/docs/project_docs/openclaw-app-metrics-dashboard/metrics-verification.md @@ -299,8 +299,264 @@ Pod `openclaw-7df8795bd7-gdskr` (2026-02-20T23:53:53Z 起動) が現行稼働中 ## 次のステップ -- [ ] `boxp/arch` リポジトリで OTel 依存追加の PR を作成（Issue #6989 のワークアラウンド） +- [x] `boxp/arch` リポジトリで OTel 依存追加の PR を作成（Issue #6989 のワークアラウンド） → **PR #7123 でマージ済み (2026-02-21)** - [ ] upstream `openclaw/openclaw` Issue #6989 にコメントで本環境の再現情報を追記 -- [ ] 新イメージビルド → ArgoCD Image Updater による自動デプロイ +- [x] 新イメージビルド → ArgoCD Image Updater による自動デプロイ → **`202602240649` で反映済み** - [ ] メトリクス出現確認 (`count({__name__=~"openclaw_.*"})`) - [ ] ダッシュボードでデータ表示を確認 + +--- + +## 再検証 (T-20260225-009): PR #7123 反映後の確認 + +### 検証日時 + +2026-02-25 16:00 UTC + +### 背景 + +`boxp/arch` PR #7123 (`feat: install opentelemetry deps in openclaw image`) が 2026-02-21 にマージされ、 +ArgoCD Image Updater により `ghcr.io/boxp/arch/openclaw:202602240649` としてデプロイ済み。 +このPRで以下の OTel パッケージが追加された: + +- `@opentelemetry/api` +- `@opentelemetry/sdk-node` +- `@opentelemetry/sdk-metrics` +- `@opentelemetry/exporter-metrics-otlp-proto` + +インストール先は `/opt/otel-deps/node_modules`、`ENV NODE_PATH="/opt/otel-deps/node_modules"` で参照可能にしている。 + +### 環境情報 + +| 項目 | 値 | +|------|-----| +| OpenClaw バージョン | v2026.2.22-2 | +| Docker イメージ | `ghcr.io/boxp/arch/openclaw:202602240649` | +| 現行 Pod | `openclaw-54446c6df9-mqw64` | +| Pod 起動時刻 | 2026-02-24T07:00:27 UTC | +| Prometheus バージョン | 3.5.0 | + +### Prometheus メトリクス確認 + +``` +list_prometheus_metric_names(regex="openclaw_.*") → [] (0件) +list_prometheus_label_values(service_name) → ["external-secrets-webhook", "longhorn-admission-webhook"] + → "openclaw" なし +target_info → 存在しない（OTel SDK 未初期化の証拠） +``` + +**全 18 ベースメトリクスが依然として Prometheus に存在しない（0/18）。** + +### Loki ログ確認（変化あり） + +#### 改善点: `@opentelemetry/api` エラー消失 + +``` +LogQL: {container="openclaw"} |~ "(?i)(otel|telemetry|Cannot find module|opentelemetry)" +期間: 2026-02-24T00:00:00Z 〜 2026-02-25T23:59:59Z +結果: 0件 +``` + +**PR #7123 の効果で `Cannot find module '@opentelemetry/api'` エラーが完全に消失した。** + +前回検証 (2026-02-21) では全 Pod 世代で発生していたこのエラーが、 +新イメージ反映後は一切発生していない。 + +#### 未改善点: プラグインロード成功ログも不在 + +``` +LogQL: {container="openclaw"} |~ "(?i)(diagnostics-otel|plugin.*load|plugin.*fail)" +期間: 2026-02-24T00:00:00Z 〜 2026-02-25T23:59:59Z +結果: 0件 +``` + +以前は `[gateway] [plugins] diagnostics-otel failed to load` というエラーが明確に出ていたが、 +現在はプラグインに関するログが**成功も失敗も一切存在しない**。 + +#### 未改善点: OTLP export 関連ログ不在 + +``` +LogQL: {container="openclaw"} |~ "(?i)(otlp|prometheus|metrics|export)" +期間: 2026-02-24T00:00:00Z 〜 2026-02-25T23:59:59Z +結果: 0件（exec コマンドログのみ、OTLP 関連はなし） +``` + +OTel SDK や Exporter の初期化・送信に関するログが一切存在しない。 + +#### 起動シーケンス分析 (2026-02-24T07:00:27) + +| 時刻 (UTC) | タグ | メッセージ | +|------------|------|----------| +| 07:00:27.609 | `[canvas]` | host mounted | +| 07:00:27.863 | `[heartbeat]` | started | +| 07:00:27.870 | `[health-monitor]` | started (interval: 300s) | +| 07:00:27.878 | `[gateway]` | agent model: openai-codex/gpt-5.3-codex | +| 07:00:27.881 | `[gateway]` | listening on ws://0.0.0.0:18789 | +| 07:00:27.887 | `[gateway]` | log file path | +| 07:00:27.891 | `[gateway]` | security warning | +| 07:00:27.926 | `[browser/service]` | ready | +| 07:00:28.252 | `[gateway]` | update available v2026.2.23 | +| 07:00:28.703 | `[delivery-recovery]` | recovery | +| 07:00:28.716 | `[discord]` | starting provider | +| 07:00:31.258 | `[telegram]` | starting provider | + +**注目: `[plugins]` タグのログが起動シーケンスに一切存在しない。** + +以前のバージョンでは: +``` +[gateway] [plugins] diagnostics-otel failed to load from /app/extensions/diagnostics-otel/index.ts +``` +というログが起動時に出ていたが、現在のバージョン (v2026.2.22-2) ではプラグインシステムの +ログ出力自体が変更された可能性がある。 + +### 診断モジュールの動作確認 + +`[diagnostic]` タグのログは正常に出力されている: + +``` +[diagnostic] stuck session: sessionId=main state=processing age=154s queueDepth=0 +[diagnostic] lane wait exceeded: lane=session:agent:main:main waitedMs=5833 queueAhead=0 +``` + +これは診断（diagnostic）モジュール自体は動作しているが、 +OTel メトリクスのエクスポート部分が機能していないことを示す。 + +### 根本原因分析 + +#### 状態変化のまとめ + +| 項目 | 前回 (2026-02-21) | 今回 (2026-02-25) | 変化 | +|------|------------------|------------------|------| +| `@opentelemetry/api` エラー | 発生 | **消失** | 改善 | +| プラグインロード失敗ログ | 発生 | **消失** | 変化 | +| プラグインロード成功ログ | なし | なし | 変化なし | +| OTLP export ログ | なし | なし | 変化なし | +| `target_info` (OTel自動生成) | なし | なし | 変化なし | +| `openclaw_*` メトリクス | 0/18 | **0/18** | 変化なし | + +#### 新たな根本原因仮説 + +PR #7123 により `@opentelemetry/api` のモジュール解決は成功するようになったが、 +メトリクスが依然として Prometheus に到達していない。以下の仮説を提示する: + +##### 仮説 1: diagnostics-otel プラグインの内部初期化失敗（最有力） + +PR #7123 は OTel パッケージを `/opt/otel-deps/node_modules` にインストールし +`NODE_PATH` で参照可能にした。`@opentelemetry/api` の import は成功するが: + +- プラグイン内部の `@opentelemetry/sdk-node` 初期化時に、 + `/app/node_modules` 内の既存パッケージとバージョン競合が発生している可能性 +- OTel SDK の NodeSDK 初期化は try-catch でラップされており、 + 失敗時にエラーログを出さず静かに失敗する実装が多い +- `target_info` すら存在しないことから、SDK 初期化自体が完了していないと推定 + +根拠: +- `@opentelemetry/api` import 成功 → エラー消失 +- `target_info` 不在 → SDK 初期化未完了 +- `[plugins]` ログ不在 → プラグインシステムの動作が不明 + +##### 仮説 2: OTLP エクスポーターの送信失敗（サイレント） + +OTel SDK は初期化に成功したが、OTLP エクスポーターが Prometheus への +HTTP POST に失敗している。OTel JS SDK のデフォルト動作では export エラーは +内部の diag handler に送られ、stderr には出力されない。 + +根拠: +- Prometheus 3.5.0 での OTLP endpoint パスが変更されている可能性 +- NetworkPolicy は設定済みだが、実際の接続テスト未実施 + +##### 仮説 3: OpenClaw v2026.2.22 でのプラグインシステム変更 + +v2026.2.22 でプラグインのロード方式が変更され、 +`/app/extensions/diagnostics-otel/` からの動的ロードが行われなくなった可能性。 + +根拠: +- `[plugins]` タグのログが一切出力されなくなった +- 起動シーケンスにプラグイン関連のフェーズが見当たらない + +#### 推定因果関係（更新版） + +``` +PR #7123 により OTel パッケージを /opt/otel-deps に追加 + → @opentelemetry/api の import エラーは解消 + → しかし、以下のいずれかが発生: + (A) SDK 初期化時にバージョン競合/内部エラーで静かに失敗 + (B) Exporter が Prometheus OTLP endpoint へのプッシュに失敗（サイレント） + (C) v2026.2.22 でプラグインシステムが変更され、拡張が読み込まれない + → いずれの場合も OTel メトリクスがエクスポートされない + → Prometheus に openclaw_* が存在しない (0/18) +``` + +### 設定面の再検証 + +| 項目 | 設定 | 状態 | +|------|------|------| +| `diagnostics.otel.enabled` | `true` | OK | +| `diagnostics.otel.metrics` | `true` | OK | +| `diagnostics.otel.endpoint` | `http://prometheus-k8s.monitoring.svc:9090/api/v1/otlp` | OK | +| `diagnostics.otel.protocol` | `http/protobuf` | OK | +| `diagnostics.otel.serviceName` | `openclaw` | OK | +| `diagnostics.otel.flushIntervalMs` | `30000` | OK | +| `plugins.entries.diagnostics-otel.enabled` | `true` | OK | +| Prometheus `otlp-write-receiver` | `enableFeatures: ["otlp-write-receiver"]` | OK | +| Prometheus バージョン | 3.5.0 | OK (OTLP はデフォルト有効) | +| NetworkPolicy (openclaw → prometheus:9090) | egress 許可 | OK | +| NetworkPolicy (prometheus ← openclaw) | ingress 許可 | OK | + +**設定面には問題なし。** + +### 対応案（更新版） + +#### 短期: OTel デバッグログの有効化 + +OpenClaw の設定に OTel diagnostics の詳細ログを有効化して原因を特定する: + +```json +{ + "diagnostics": { + "otel": { + "debug": true + } + } +} +``` + +または環境変数でOTel SDK のデバッグログを有効化: + +```yaml +env: + - name: OTEL_LOG_LEVEL + value: "debug" + - name: OTEL_TRACES_EXPORTER + value: "none" + - name: OTEL_METRICS_EXPORTER + value: "otlp" +``` + +#### 短期: OpenClaw v2026.2.23 へのアップデート + +起動ログで `update available (latest): v2026.2.23 (current v2026.2.22-2)` と表示されている。 +v2026.2.23 で OTel プラグインの修正が含まれている可能性がある。 + +#### 中期: boxp/arch Dockerfile での OTel パッケージインストール方法の見直し + +PR #7123 の `/opt/otel-deps` + `NODE_PATH` 方式が動作しない場合、 +`/app/node_modules` 内に直接インストールする方式に変更: + +```dockerfile +USER root +RUN cd /app && npm install --no-save \ + @opentelemetry/api \ + @opentelemetry/sdk-node \ + @opentelemetry/sdk-metrics \ + @opentelemetry/exporter-metrics-otlp-proto +USER node +``` + +### 次のステップ + +- [ ] ConfigMap に `OTEL_LOG_LEVEL=debug` 環境変数を追加して再デプロイし、OTel 内部エラーを特定 +- [ ] OpenClaw v2026.2.23 で diagnostics-otel の挙動変更がないか changelog を確認 +- [ ] v2026.2.23 へのアップデートを検討 +- [ ] 改善しない場合、OTel パッケージを `/app/node_modules` に直接インストールする方式に変更 +- [ ] upstream `openclaw/openclaw` Issue #6989 の進捗を確認