トラブルシューティング¶
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++ の初期化または読み込みの失敗¶
- アプリ、インポートライブラリ、
guance_windows_native.dllが同じアーキテクチャであることを確認します。現在の vcpkg ポートは動的x64-windowsのみを提供するため、他のアーキテクチャでは一致するアーキテクチャのソースビルド成果物を使用する必要があります。 - DLL がアプリケーションディレクトリまたは Windows の DLL 検索パスにあることを確認します。NuGet パッケージ内の x86、x64、ARM64 Native ランタイムアセットは .NET ラッパーレイヤー向けであり、C/C++ ヘッダーファイルやインポートライブラリと同等ではありません。
- 最初に
guance_sdk_config_init()を呼び出してから、アドレス、Token、App ID、サービス名、バージョン、環境を設定します。 - パブリック DataWay ではアドレスと Client Token が必要です。ローカル環境(Datakit)では、アクセス可能な Datakit アドレスを設定する必要があります。
guance_sdk_init()が空の Handle を返す場合は、必須項目、キャッシュディレクトリの権限、プロセスアーキテクチャを確認します。
SDK は正常に動作するがデータがない¶
コンソールに RUM データがない¶
次の順に確認します。
- App ID が現在のワークスペースの「カスタム」アプリと一致しているか。
- パブリック DataWay で、正しいベースアドレスと Client Token の両方が設定されているか。
- ローカル環境(Datakit)にアプリケーションプロセスからアクセスでき、RUM コレクターが有効になっているか。
- RUM の
SampleRateまたはsample_rateが0より大きいか。 - View を開始しているか、対応する自動収集を有効にしているか。
- アプリ終了前に、シャットダウン 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 データがない¶
GuanceConfig.Loggingが設定され、EnableCustomLog = trueであることを確認します。SampleRateとLevelFiltersを確認し、メッセージが UTF-8 の 30 KiB 上限を超えていないかを確認します。System.Diagnostics.Traceの出力は SDK によって自動転送されません。アプリの既存のログ出力ポイントでAddLog()またはAddLogs()を明示的に呼び出してください。GetLogDiagnosticsSnapshot()を取得し、設定、サンプリング、レベル、容量による破棄カウントをそれぞれ確認します。
- 最初に
guance_log_config_init()を呼び出し、次にguance_log_configure()を呼び出します。 enable_custom_logが1であることを確認し、sample_rateとlevel_filter_maskを確認します。- Native SDK は Console、ETW、サードパーティ製ログライブラリを自動的にインターセプトしません。既存のログ出力ポイントで
guance_log_add()またはguance_log_add_batch()を呼び出してください。 guance_log_get_diagnostics()を使用して、キュー投入、破棄、リトライ、最後のステータスコードを確認します。
Log と RUM は独立したキューを使用します。RUM が正常でも Log が有効であるとは限りません。逆も同様です。
リクエストに Trace Header がない¶
EnableAutoTraceまたはenable_auto_traceが有効になっていることを確認します。- サンプルレートが
0でないことを確認し、対象 URL がShouldTraceまたはshould_traceを通過しているかを確認します。 - サーバー側で要求される伝播形式が
TraceTypeまたはtrace_typeと一致しているかを確認します。 - Trace Header は選択した形式によって決まります。
trace_idという名前の HTTP Header だけを検索しないでください。 - 信頼できない宛先に 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 にページデータがない¶
- WebView2 Runtime がインストールされており、コントロールが
EnsureCoreWebView2Async()を完了できることを確認します。 EnableWebView = trueであることを確認するか、AttachWebView()を明示的に呼び出します。- 動的コントロールでは、初期化完了後に明示的に関連付けることを推奨します。
- コントロールが
UnloadedまたはDisposedになった後は、新しいインスタンスで再び関連付ける必要があります。 - 診断リスナーを登録し、
WebView2 initialization failedまたはdid not succeedを確認します。
同じコントロールに対して AttachWebView() を繰り返し呼び出しても、重複して注入されることはありません。ページ自体でも Browser RUM が初期化されている場合は、同じページイベントを手動で重複して報告しないでください。
Electron にデータがない¶
最初に、アプリがどの Electron 接続方式を使用しているかを確認します。2つの方式では Session とアップロードの所有者が異なるため、設定を混在させることはできません。
- Full Mode では、npm でダウンロードしたランタイム、または CLI が指定した
native.directoryを確認します。Mixed Mode では、C++ ホストが SDK を初期化し、native.pipeNameに一致する Bridge Server を起動していることを確認します。両モードのインストール手順は Electron モニタリング を参照してください。 - Full Mode のパッケージディレクトリは、ASAR の外側にある
resources/native/です。同じバージョン・同じアーキテクチャの Bridge EXE、基本 DLL、マニフェストを含める必要があります。Replay を使用する場合は、追加 DLL とreplay-manifest.jsonも含める必要があります。Mixed Mode では、ホストが基本 DLL とオプションの DLL を配置します。 - Full Mode では、
native.settingsによって完全な Native 設定を提供し、起動とコンポーネント読み込みの診断を確認します。終了コード2は送信先アドレスまたは RUM Application ID の不足を示します。終了コード3は Native Core の初期化または Log 設定の失敗を示します。 - Browser RUM/Logs は、監視対象の Renderer でのみ初期化されます。各ウィンドウで Preload をインストールし、信頼された
webContentsを登録して、最小限の初期化を 1 回実行する必要があります。Renderer には、Bridge モードに必要なプレースホルダーパラメータのみを設定し、実際の Token、App ID、送信先アドレスは設定しないでください。 - Renderer の DevTools Network に、RUM、Log、Replay の直接アップロードリクエストが表示されないようにします。固定 IPC Channel がメッセージを受信しているか、Main Process が信頼された Renderer を受け入れているかを確認します。Full Mode では Bridge EXE の stdin/stdout 転送を確認し、Mixed Mode では named-pipe 接続を確認します。
- 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 が有効でもデータがない¶
- .NET を NuGet
0.1.0-alpha.9にアップグレードした後、同じバージョンのGuance.Windows.SessionReplayがインストールされていることを確認します。初期化時に設定したDiagnosticListenerを通じてsession_replay_componentを確認し、パッケージ不足、バージョン不一致、読み込み失敗を区別します。 - Native を vcpkg
0.1.0-alpha.10にアップグレードした後、replayFeature が有効になっていること、Replay DLL が基本 DLL と同じ場所にあり、バージョンとアーキテクチャが一致していることを確認します。標準エラー出力の Replay コンポーネント診断も確認し、session_replay_enabledだけを確認しないでください。 - クライアントの
IsSessionReplayAvailableまたはguance_rum_is_session_replay_available()を使用してコンポーネントが利用可能であることを確認してから、サンプルレート、アクティブな View、録画の開始・停止状態を確認します。コンポーネントが利用可能でも、現在の Session がサンプリングされているとは限りません。 - Electron Full Mode では、
--with-replayまたは--replay-archiveを使用して追加コンポーネントをインストール・パッケージングしていることを確認します。Mixed Mode では、ホスト Native と Bridge Server の両方で Replay が有効になっていることを確認します。WebView2/Electron のgetCapabilities()にrecordsが含まれていない場合、ページで録画を強制開始しないでください。
基本パッケージのみをインストールしている場合でも、通常の RUM、Log、Trace は動作します。具体的なインストール方法は オプションコンポーネントのインストール を参照してください。
終了時にキュー内のデータが残っている¶
非同期シャットダウンをトリガーしただけで、その直後にプロセスを終了しないでください。Native のクラッシュ Error は次回起動時に復元され、キューに投入されます。クラッシュしたプロセス内でネットワークアップロードは実行されません。
Debug モードを有効にする¶
Native はテスト環境で debug = 1 を設定します。C# には実行時の Debug 設定フィールドがないため、初期化設定の DiagnosticListener または GuanceSdk.AddDiagnosticListener() を使用して、SDK レベル、ソース、メッセージを記録できます。問題を報告する際は、以下を提供してください。
- SDK バージョン、ランタイムまたはコンパイラのバージョン、Windows バージョン
- UI フレームワーク、プロセスアーキテクチャ、組み込み言語
- マスク処理済みの設定
- RUM と Log の診断カウント、ステータスコード
- 再現可能な最小手順
Client Token、認証 Header、Cookie、ユーザーの機密情報、ローカルの絶対パスは提出しないでください。