トラブルシューティング¶

SDK 初期化時の異常チェック¶

.NET / C# 設定の検証¶

GuanceSdk.Init() は呼び出し時に重要な設定を即座に検証します：

Native C/C++ の初期化または読み込みの失敗¶

1. アプリケーション、インポートライブラリ、guance_windows_native.dll がすべて同じアーキテクチャであることを確認してください。現在の vcpkg ポートは動的 x64-windows のみを提供します。他のアーキテクチャでは、対応するアーキテクチャのソースコードからビルドした成果物を使用する必要があります。
2. DLL がアプリケーションディレクトリまたは Windows DLL 検索パス内に存在することを確認してください。NuGet パッケージ内の x86、x64、ARM64 各 Native ランタイムアセットは .NET ラッパー層で使用されるものであり、C/C++ のヘッダーファイルやインポートライブラリとは異なります。
3. 最初に guance_sdk_config_init() を呼び出し、その後アドレス、Token、アプリケーション ID、サービス名、バージョン、環境を設定してください。
4. パブリックネットワーク DataWay の場合はアドレスと Client Token が必要です。ローカル環境（Datakit）にデプロイする場合は、アクセス可能な Datakit アドレスを設定してください。
5. guance_sdk_init() が空の Handle を返す場合は、必須項目、キャッシュディレクトリの権限、プロセスアーキテクチャを確認してください。

SDK は正常に動作しているがデータがない¶

コンソールに RUM データがない¶

以下の項目を順に確認してください：

1. App ID が現在のワークスペースの「カスタム」アプリケーションと一致しているか。
2. パブリックネットワーク DataWay に、正しいベースアドレスと Client Token の両方が設定されているか。
3. ローカル環境（Datakit）にアプリケーションプロセスからアクセス可能で、RUM コレクターが有効になっているか。
4. RUM の SampleRate または sample_rate が 0 より大きいか。
5. View がすでに開始されているか、対応する自動収集が有効になっているか。
6. アプリケーション終了前に、待機またはクローズ API の呼び出しが行われているか。

var snapshot = GuanceSdk.GetDiagnosticsSnapshot();
Console.WriteLine(
    $"sampled={snapshot.SessionSampled}, " +
    $"enqueued={snapshot.RumEventsEnqueued}, " +
    $"uploaded={snapshot.RumUploadSuccessCount}, " +
    $"retry={snapshot.RumUploadRetryCount}, " +
    $"terminal={snapshot.RumUploadTerminalFailureCount}, " +
    $"lastStatus={snapshot.LastRumUploadStatusCode}, " +
    $"lastError={snapshot.LastRumUploadError}");

guance_sdk_diagnostics diagnostics{};
if (guance_sdk_get_diagnostics(rum, &diagnostics)) {
    printf("queued=%lld uploaded=%lld retries=%lld status=%lld error=%lld\n",
        static_cast<long long>(diagnostics.rum_events_enqueued),
        static_cast<long long>(diagnostics.rum_upload_success_count),
        static_cast<long long>(diagnostics.rum_upload_retry_count),
        static_cast<long long>(diagnostics.last_rum_upload_status_code),
        static_cast<long long>(diagnostics.last_rum_upload_error_code));
}

エンキューカウントが 0 の場合は、まずサンプリング、View、収集スイッチを確認してください。リトライが増加し続ける場合は、ネットワーク、プロキシ、DNS、送信先アドレスを確認してください。最終失敗が増加する場合は、Token、権限、サーバー側のステータスコードを確認してください。

デスクトップ UI に View や Action がない¶

WPF および WinForms¶

• 最初のウィンドウが作成される前に EnableAutomaticInstrumentation() を呼び出してください。
• EnableWpf または EnableWinForms が無効になっていないか確認してください。
• 重要なコントロールには、安定した Name、タイトル、またはアクセシビリティ名を設定してください。
• 動的 WinForms コントロールは Application Idle 時にスキャンされます。メッセージループが長時間アイドル状態にならない場合、検出が遅れる可能性があります。

WinUI 3¶

WinUI 3 ウィンドウは Activate() の前に明示的に関連付ける必要があります。マルチウィンドウアプリケーションでは、各ウィンドウを個別に関連付けてください：

window = new MainWindow().UseGuanceRum("MainWindow");
// または GuanceSdk.AttachWinUIWindow(window, "MainWindow");
window.Activate();

Native C/C++¶

• ウィンドウ作成後に guance_rum_start_view() を呼び出し、ウィンドウクローズ前に guance_rum_stop_view() を呼び出してください。
• Action は、コマンド、メニュー、または入力メッセージ処理の境界で明示的に開始および終了する必要があります。
• UI Watchdog は、現在のプロセスが所有する有効なトップレベル HWND を必要とします。
• Native SDK は汎用のウィンドウフックやコントロールフックをインストールしないため、すべての MFC やカスタムフレームワークのイベントを自動検出することはできません。

ログデータがない¶

ログと RUM は独立したキューを使用します。RUM が正常でもログが有効であるとは限りません。その逆も同様です。

リクエストに Trace Header がない¶

1. EnableAutoTrace または enable_auto_trace が有効になっているか確認してください。
2. サンプリングレートが 0 ではないこと、および対象 URL が ShouldTrace または should_trace を通過しているか確認してください。
3. サーバー側が要求する伝搬フォーマットと TraceType または trace_type が一致しているか確認してください。
4. Trace Header は選択されたフォーマットによって決まります。trace_id という名前の HTTP Header だけを探さないでください。
5. 信頼できない送信先に Trace Header を公開しないでください。

リクエストにすでに同名の Trace Header が存在する場合は、SDK が注入した後に HTTP ライブラリやビジネスコードがそれを上書きしていないか確認してください。

Trace または Log が RUM に関連付けられていない¶

• Trace/Log 設定の EnableLinkRumData または enable_link_rum_data をそれぞれ有効にしてください。
• アクティブな View または Action が存在する状態でリクエストを送信するか、ログを書き込んでください。SDK はすでに終了したコンテキストを遡及的に変更しません。
• Trace 関連付け情報は、対応する RUM Resource に書き込まれます。Windows SDK は独立して APM Span をアップロードしないため、Trace コンソールに Span がなくても、Header の注入が失敗したとは限りません。

WebView2 にページデータがない¶

1. WebView2 Runtime がインストールされており、コントロールが EnsureCoreWebView2Async() を完了できるか確認してください。
2. EnableWebView = true であること、または AttachWebView() が明示的に呼び出されていることを確認してください。
3. 動的コントロールの場合は、初期化完了後に明示的に関連付けることをお勧めします。
4. コントロールが Unloaded または Disposed になった後は、新しいインスタンスで再度関連付ける必要があります。
5. 診断リスナーを登録し、WebView2 initialization failed または did not succeed を確認してください。

同じコントロールに対して AttachWebView() を繰り返し呼び出しても、再注入は行われません。ページ自体がすでに Browser RUM を初期化している場合は、同じページイベントを手動で重複して報告しないでください。

Electron にデータがない¶

まず、アプリケーションがどの Electron 接続方式を採用しているか確認してください。2 つの方式では Session とアップロードの所有者が異なり、設定を混在させることはできません。

データの重複¶

• アプリケーション起動中に、対応する SDK Handle は一度だけ初期化してください。
• .NET で GuanceSdk.Init() を繰り返し呼び出すと、古いクライアントが非同期に解放され、初期化の境界が重なって重複収集が発生する可能性があります。
• 自動収集がすでにカバーしているコントロールの操作、HttpClient リクエスト、または WinHTTP リクエストを手動で再度報告しないでください。
• WinUI 3 では、同じウィンドウに対して 1 つの関連付け方法のみを使用してください。
• Electron renderer は、初期化エントリが一度だけ実行されるようにしてください。

終了時にキューにデータが残っている¶

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

非同期クローズをトリガーした後、すぐにプロセスを終了しないでください。Native のクラッシュ Error は、次回起動時に復旧されキューに追加されますが、クラッシュしたプロセス内でネットワークアップロードが実行されることはありません。

デバッグモードを有効にする¶

テスト環境で Debug = true または debug = 1 を有効にしてください。C# では GuanceSdk.AddDiagnosticListener() を使用して、SDK レベル、ソース、メッセージを記録できます。問題を報告する際は、以下を提供してください：

• SDK バージョン、ランタイムまたはコンパイラバージョン、Windows バージョン；
• UI フレームワーク、プロセスアーキテクチャ、接続言語；
• マスク処理済みの設定；
• RUM と Log の診断カウント、ステータスコード；
• 再現可能な最小手順。

Client Token、認証 Header、Cookie、ユーザーの機密情報、またはローカルの絶対パスは提出しないでください。