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

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 は汎用のウィンドウまたはコントロールの Hook をインストールしないため、すべての MFC またはカスタムフレームワークのイベントを自動的に検出しません。

Log データがない¶

Log と RUM は独立したキューを使用します。RUM が正常でも Log が有効になっているとは限りません。逆も同様です。

リクエストに 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 がすでにある場合は、HTTP ライブラリまたはビジネスコードが SDK の注入後にそれを上書きしていないか確認してください。

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

• Trace/Log 設定の EnableLinkRumData または enable_link_rum_data をそれぞれ有効にしてください。
• アクティブな View または Action が存在するときに、リクエストを送信するか Log を書き込みます。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 では、初期化エントリポイントが 1 回だけ実行されるようにしてください。

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

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

非同期シャットダウンをトリガーしただけで、その直後にプロセスを終了しないでください。Native のクラッシュ Error は次回起動時に復元され、キューに入れられます。クラッシュしたプロセス内でネットワークアップロードは実行されません。

Debug デバッグを有効にする¶

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

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

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