nemo-relay-debug-runtime-integration

ランタイム統合のデバッグ

アプリケーションに NeMo Relay が存在するものの、何かが正常に動作しない場合に、このスキルを使用します。 設定を変更する前に、まずどのランタイムレイヤーで問題が起きているかを確認してください。

最初に確認すること

• バインディングまたはネイティブ成果物を読み込めますか？
• 問題の呼び出しが実行されるとき、アクティブなスコープがありますか？
• 想定したスコープスタック上で処理が実行されていますか？
• サブスクライバー、エクスポーター、プラグインの設定は実際に有効ですか？
• アプリケーションでは適切な公開 API レイヤーが選択されていますか？：マネージド実行、手動ライフサイクル、型付きラッパー、またはアダプティブ／プラグイン

よくある障害の種類

• Python ネイティブ拡張が見つからない
• Go の動的ライブラリがローダーのパスにない
• Node のネイティブアドオンがビルドされていない、または読み込まれていない
• スコープ外での実行呼び出し
• 登録が行われていないためイベントが欠落する
• 並行処理により、誤ったスコープスタックがアクティブになる
• アダプティブコンポーネントが初期化されない、または設定の検証が無視される

埋め込みトラブルシューティングマトリックス

• Rust のビルド失敗：まず対象を最小限に絞ったコアビルドを実行し、その後、影響を受けるバインディングまたはワークスペースのコマンドまで範囲を広げます。
• Python のインポート失敗：uv sync で仮想環境とネイティブ拡張を再構築し、アプリケーションと同じ環境から簡単な Python テストまたはインポート確認を実行します。
• Node.js アドオンの失敗：アプリケーションコードをデバッグする前に、Node バインディングパッケージからネイティブアドオンを再インストールして再ビルドします。
• Go ローダーの失敗：リリース版の FFI 共有ライブラリをビルドし、リンカーとランタイムローダーの両方がリリース出力ディレクトリを参照するようにします。macOS では、macOS の動的ライブラリパス変数（DYLD_LIBRARY_PATH）を使用します。
• スコープスタックが空：アクティブなスコープの外で処理が行われているか、意図したスタックを伴わずにスレッド、タスク、goroutine、またはワーカーの境界を越えています。
• 処理がリクエスト間で漏れる：個別のリクエストが1つのスコープスタックを共有しています。独立したリクエストまたはエージェントごとに、新しいスタックを作成してください。
• ミドルウェアがない、または順序が正しくない：グローバル登録とスコープローカル登録、アクティブなスコープの祖先、名前、優先度の値を確認します。
• サブスクライバーにイベントが届かない：イベントが発行される前に登録してください。スコープローカルのサブスクライバーでは、現在のスコープがオーナーまたはその子孫であることを確認します。
• イベントフィールドが欠落する：マネージドヘルパーは意味的なフィールドを設定します。手動のライフサイクル呼び出しでは、入力、出力、モデル名、ツール呼び出し ID のパラメーターを明示的に指定する必要があります。
• ATIF が空、または混在している：処理の開始前に登録し、1回の実行につきエクスポーターを1つ使用するか、実行間でクリアします。また、ルートスコープによって並行するエージェントを分離します。
• プロバイダーペイロードの変換失敗：JSON 以外のプロバイダーオブジェクト、SDK ハンドル、コールバック、ストリーム、またはクラスインスタンスは、明示的なコーデックを使って変換します。
• プラグインの検証失敗：設定の検証はランタイム登録とは個別に行い、必須フィールド、値の型、デフォルト値、設定ソースを確認します。
• アダプティブ動作が変わらない：計装によってイベントが発行されていること、アダプティブコンポーネントが有効であること、ポリシーがその動作を許可していること、呼び出しパスが設定済みのコンポーネントに到達することを確認します。
• OpenTelemetry または OpenInference のエクスポート失敗：まず Relay のバージョンを特定します。0.6 の場合は、別のエクスポーター、http_binary と grpc の違い、エンドポイント、ヘッダー、ターゲットのサポート、ネイティブ gRPC 用のアクティブな Tokio ランタイムを確認します。0.7 の場合は、型付きプロジェクション、エンドポイント、ヘッダー、TLS、ターゲットのサポートを確認します。ネイティブ gRPC のランタイムはサブスクライバーが管理します。
• コールバックは成功したが、ライフサイクルイベントが現れない：統合で、基盤となるビジネスコールバックだけでなく、マネージド実行ヘルパーまたは開始／終了の対応が取れた手動 API を使用していることを確認します。

関連スキル

• nemo-relay-get-started
• nemo-relay-instrument-context-isolation
• nemo-relay-plugin-adaptive-tuning
• nemo-relay-plugin-build