コンテンツにスキップ

トラブルシューティング

SDK 初期化時の設定検証

.NET / C# 設定の検証

GuanceSdk.Init() は、重要な設定を即座に検証します。

エラー内容 対処方法
RumAppId is required. コンソールで作成した App ID を設定します。
ServiceName is required. 空でない ServiceName を設定します。
Version is required. アプリのバージョンを設定します。
Env must be one of... prod、gray、pre、common、local のいずれかを使用します。
Either DatawayUrl or DatakitUrl is required. 送信先アドレスを少なくとも 1 つ設定します。
ClientToken is required when DatawayUrl is configured. パブリック DataWay モードの場合は Client Token を追加します。
SampleRate must be between 0 and 1. サンプルレートを 0.0~1.0 の範囲に設定します。

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、App 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 データがない

  1. GuanceConfig.Logging が設定され、EnableCustomLog = true であることを確認します。
  2. SampleRate と LevelFilters を確認し、メッセージが UTF-8 の 30 KiB 上限を超えていないかを確認します。
  3. System.Diagnostics.Trace の出力は SDK によって自動転送されません。アプリの既存のログ出力ポイントで AddLog() または AddLogs() を明示的に呼び出してください。
  4. GetLogDiagnosticsSnapshot() を取得し、設定、サンプリング、レベル、容量による破棄カウントをそれぞれ確認します。
  1. 最初に guance_log_config_init() を呼び出し、次に guance_log_configure() を呼び出します。
  2. enable_custom_log が 1 であることを確認し、sample_rate と level_filter_mask を確認します。
  3. Native SDK は Console、ETW、サードパーティ製ログライブラリを自動的にインターセプトしません。既存のログ出力ポイントで guance_log_add() または guance_log_add_batch() を呼び出してください。
  4. guance_log_get_diagnostics() を使用して、キュー投入、破棄、リトライ、最後のステータスコードを確認します。

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 を送信しないでください。

自動診断サブスクリプションには、AutomaticInstrumentationOptions.EnableHttpClient = true が必要です。カスタム HttpClient パイプラインでは、GuanceSdk.CreateHttpMessageHandler() を明示的に使用できます。

WinHTTP リクエストでは、guance_rum_winhttp.hpp アダプターを使用する必要があります。その他の HTTP ライブラリでは、guance_trace_create_context() を呼び出し、返された Header をリクエストに書き込む必要があります。

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

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 とアップロードの所有者が異なるため、設定を混在させることはできません。

  1. Full Mode では、npm でダウンロードしたランタイム、または CLI が指定した native.directory を確認します。Mixed Mode では、C++ ホストが SDK を初期化し、native.pipeName に一致する Bridge Server を起動していることを確認します。両モードのインストール手順は Electron モニタリング を参照してください。
  2. Full Mode のパッケージディレクトリは、ASAR の外側にある resources/native/ です。同じバージョン・同じアーキテクチャの Bridge EXE、基本 DLL、マニフェストを含める必要があります。Replay を使用する場合は、追加 DLL と replay-manifest.json も含める必要があります。Mixed Mode では、ホストが基本 DLL とオプションの DLL を配置します。
  3. Full Mode では、native.settings によって完全な Native 設定を提供し、起動とコンポーネント読み込みの診断を確認します。終了コード 2 は送信先アドレスまたは RUM Application ID の不足を示します。終了コード 3 は Native Core の初期化または Log 設定の失敗を示します。
  4. Browser RUM/Logs は、監視対象の Renderer でのみ初期化されます。各ウィンドウで Preload をインストールし、信頼された webContents を登録して、最小限の初期化を 1 回実行する必要があります。Renderer には、Bridge モードに必要なプレースホルダーパラメータのみを設定し、実際の Token、App ID、送信先アドレスは設定しないでください。
  5. Renderer の DevTools Network に、RUM、Log、Replay の直接アップロードリクエストが表示されないようにします。固定 IPC Channel がメッセージを受信しているか、Main Process が信頼された Renderer を受け入れているかを確認します。Full Mode では Bridge EXE の stdin/stdout 転送を確認し、Mixed Mode では named-pipe 接続を確認します。
  6. Native Host の RUM、Log、Replay のキュー投入数、アップロードステータスコード、リトライ、最終失敗数を確認します。アプリ終了時は、Adapter の stop() が完了するのを待ちます。Mixed Mode では、さらにホストが自身の SDK Handle を閉じ、キュー内のデータが失われないようにします。

Bridge は Electron の Main Process Crash を自動的にキャプチャできません。Renderer の unresponsive と render-process-gone は Main Process でリッスンし、信頼された Bridge コマンドに変換する必要があります。完全な導入方法は Electron モニタリング を参照してください。

  • Browser RUM は Renderer でのみ初期化されます。独立した各 Renderer ページで初期化する必要があります。
  • file:// ページでは sessionPersistence: "local-storage" を設定します。
  • Main Process は RUM インスタンスをリモートページに自動的に渡しません。
  • Browser RUM の applicationId、site/datakitOrigin、Token、サンプルレートを確認します。
  • このモードでは Windows Native Bridge は起動されません。完全なトラブルシューティング手順は Web RUM Electron アプリの導入 を参照してください。

データの重複

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

Replay が有効でもデータがない

  1. .NET を NuGet 0.1.0-alpha.9 にアップグレードした後、同じバージョンの Guance.Windows.SessionReplay がインストールされていることを確認します。初期化時に設定した DiagnosticListener を通じて session_replay_component を確認し、パッケージ不足、バージョン不一致、読み込み失敗を区別します。
  2. Native を vcpkg 0.1.0-alpha.10 にアップグレードした後、replay Feature が有効になっていること、Replay DLL が基本 DLL と同じ場所にあり、バージョンとアーキテクチャが一致していることを確認します。標準エラー出力の Replay コンポーネント診断も確認し、session_replay_enabled だけを確認しないでください。
  3. クライアントの IsSessionReplayAvailable または guance_rum_is_session_replay_available() を使用してコンポーネントが利用可能であることを確認してから、サンプルレート、アクティブな View、録画の開始・停止状態を確認します。コンポーネントが利用可能でも、現在の Session がサンプリングされているとは限りません。
  4. Electron Full Mode では、--with-replay または --replay-archive を使用して追加コンポーネントをインストール・パッケージングしていることを確認します。Mixed Mode では、ホスト Native と Bridge Server の両方で Replay が有効になっていることを確認します。WebView2/Electron の getCapabilities() に records が含まれていない場合、ページで録画を強制開始しないでください。

基本パッケージのみをインストールしている場合でも、通常の RUM、Log、Trace は動作します。具体的なインストール方法は オプションコンポーネントのインストール を参照してください。

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

await GuanceSdk.ShutdownAsync();
guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

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

Debug モードを有効にする

Native はテスト環境で debug = 1 を設定します。C# には実行時の Debug 設定フィールドがないため、初期化設定の DiagnosticListener または GuanceSdk.AddDiagnosticListener() を使用して、SDK レベル、ソース、メッセージを記録できます。問題を報告する際は、以下を提供してください。

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

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

フィードバック

このページは役に立ちましたか?