コンテンツにスキップ

Windows アプリケーションデータ収集

Windows ドキュメントは RUM、Log、HTTP Trace の 3 種類のデータ機能をカバーします。.NET / C#、Native C/C++、WebView2、Electron ネイティブ Bridge は同じ Windows SDK の製品 ID を使用します。Electron Renderer の Browser RUM は収集とシリアライズのみを担当し、信頼フィールドと Session は Main Process アダプトレイヤーと Windows Native Core が統合管理し、キューとアップロードは Native Core が引き継ぎます。

データ種別

データ区分 用途 送信動作
RUM Session、View、Action、Resource、Error、Long Task を記録 RUM キューに書き込み、RUM Intake に送信
Log アプリケーションログを記録し、現在の RUM コンテキストに関連付け可能 独立した Log キューに書き込み、Logging Intake に送信
HTTP Trace 送信リクエストに Trace Header を注入し、対応する RUM Resource に関連付け可能 APM Span を単独で送信しない

グローバル属性

フィールド 型 説明
app_id string コンソールで作成したアプリケーション ID。
service string .NET では GuanceConfig.ServiceName、Native では guance_sdk_config.service_name、Electron ではネイティブ設定を使用。
env string prod、gray、pre、common、local のいずれか。
version string アプリケーションバージョン。
sdk_name string Windows .NET、Native Core、WebView2、Electron ネイティブ Bridge では df_windows_rum_sdk に固定。
sdk_version string 現在のホスト Windows SDK アセンブリまたは Native Core のバージョン。WebView2 と Electron のデータはこの識別情報を引き継ぎます。
sdk_pkg_info string SDK が自動生成する JSON 文字列で、適用される Browser SDK および Electron Adapter パッケージのバージョンを記録します。詳細は下記を参照。
application_uuid string 現在のアプリケーションインストールインスタンスの識別子。
session_id string 現在のユーザー Session 識別子。
session_type string Windows SDK では user に固定。
session_has_replay boolean 現在の Session がアップロード可能な Replay データを生成済みかどうか。
session_sample_rate number 現在の通常 Session のサンプリングレート。
session_on_error_sample_rate number Error Session の追加サンプリングレート。
view_id string 現在アクティブな View の識別子。
action_id string 現在アクティブな Action の識別子。存在する場合に書き込みます。
userid string RUM アプリケーション ID ごとに永続化される匿名ユーザー識別子、またはユーザー API で設定されたユーザー ID。
user_name、user_email string ユーザー API 呼び出しにより設定された後に書き込みます。
is_signin string ユーザー設定済みの場合は T、それ以外は F。
os、os_version string Windows の名前とバージョン。
os_version_major string Windows のメジャーバージョン。
device、model string Windows のデバイスとモデル情報。取得できる場合に書き込みます。
arch string プロセスが実行されているデバイスのアーキテクチャ。
screen_size string 取得できる場合にメインディスプレイのサイズを記録します。
locale string 現在のロケール設定。
network_type string wifi、ethernet、mobile、none、unknown のいずれか。

カスタムコンテキストは既存フィールドを補完するだけで、SDK 予約フィールドを上書きできません。

SDK コンポーネントバージョン

sdk_pkg_info は NuGet / Native SDK 0.1.0-alpha.11 以降でサポートされます。Electron 統合では @cloudcare/electron-native-adapter 0.1.0-alpha.6 以降を同時に使用する必要があり、Full Mode と Mixed Mode のルールは同じです。このフィールドを手動で設定する必要はありません。

  • web:現在の Browser RUM または Browser Log イベントが提供する Browser SDK のバージョン。
  • electron:インストール済みの @cloudcare/electron-native-adapter npm パッケージのバージョン。

次に Browser SDK 3.3.6 と Electron Adapter 0.1.0-alpha.6 を例に、JSON 文字列の内容を表に示します。

データソース sdk_pkg_info の例
.NET WebView2 内の Browser RUM {"web":"3.3.6"}
Adapter 接続後の Electron ホスト RUM / Log {"electron":"0.1.0-alpha.6"}
Electron Browser RUM / Log(Full Mode または Mixed Mode) {"electron":"0.1.0-alpha.6","web":"3.3.6"}
Browser バージョンがなく、Electron Adapter にも接続していない .NET / Native データ このフィールドは書き込みません

Browser イベントにバージョンがない場合は web を省略し、Electron Adapter 接続時は electron を保持します。フィールドには agent、native、replay は含まれません。sdk_name、sdk_version はホスト Windows SDK の識別を継続し、Browser と Adapter のバージョンはコンポーネント情報としてのみ記録されます。

フィールドはホスト SDK が実際のコンポーネントバージョンに基づいて生成するため、ページから渡された sdk_pkg_info を直接使用しません。WebView2 の Browser RUM Bridge は、Replay が無効な場合やオプションの Replay コンポーネントがインストールされていない場合でも使用できます。

その他のデータタイプの属性

Session は、コンソールが同じ session_id のイベントを集約して生成するユーザーアクセスプロセスであり、Session API を個別に呼び出す必要はありません。

タイプ 説明 代表的な発生源
View ウィンドウまたはビジネスページの可視期間とパフォーマンス Window/Form のライフサイクル、WinUI 3 の明示的な関連付け、Native ウィンドウイベント、WebView2 ナビゲーション
Action ユーザー操作とその所要時間 クリック、メニュー、選択、切り替え、入力、ショートカットキー、または手動 Action
Resource ネットワークリクエスト、ステータス、所要時間 HttpClient、WinHTTP、WebView2 Fetch/XHR/Resource、または手動 Resource
Error アプリケーションおよびページのエラー 未処理の .NET 例外、Native クラッシュの復元、WebView2 JavaScript Error、または手動 Error
Long Task UI メインスレッドの長時間ブロック Windows UI スレッドの検出または手動 Long Task

View

フィールド 型 説明
view_id string View の一意の識別子。
view_name string ウィンドウ、ページ、またはビジネス View の名前。
view_referrer string 直前の View 名。
time_spent integer View の継続時間(ナノ秒単位)。
is_active boolean 送信時に View がまだアクティブかどうか。
view_action_count integer View 内で発生した Action の数。
view_resource_count integer View 内で発生した Resource の数。
view_error_count integer View 内で発生した Error の数。
view_long_task_count integer View 内で発生した Long Task の数。
view_update_time integer 今回の View 更新の Unix ナノ秒タイムスタンプ。

Action

フィールド 型 説明
action_id string Action の一意の識別子。
action_name string コントロール、コマンド、またはビジネスアクションの名前。
action_type string 例:click、key、launch_cold、launch_hot。
duration integer Action の継続時間(ナノ秒単位)。
action_resource_count integer Action スコープ内の Resource の数。
action_error_count integer Action スコープ内の Error の数。
action_long_task_count integer Action スコープ内の Long Task の数。
app_pre_application_init_time integer 起動 Action 内の、アプリケーションコード実行前の所要時間。
app_application_init_time integer 起動 Action 内の、アプリケーション初期化フェーズの所要時間。
app_first_frame_init_time integer 起動 Action 内の、ファーストフレームフェーズの所要時間。

Resource

フィールド 型 説明
resource_id string Resource の一意の識別子。
resource_url string プライバシーポリシー処理後のリクエスト URL。
resource_url_host string リクエストのホスト名。
resource_url_path string リクエストパス。
resource_url_path_group string 正規化されたパスグループ。
resource_method string HTTP メソッド。
resource_status integer HTTP ステータスコード。応答を取得できない場合は有効なステータスを書き込みません。
resource_status_group string ステータスコードのグループ。例:2xx。
resource_type string http、native、またはアプリケーションが渡したリソースタイプ。
duration integer Resource の合計所要時間(ナノ秒単位)。
resource_size integer レスポンスボディのバイト数。取得できる場合に書き込みます。
resource_request_size integer リクエストボディのバイト数。取得できる場合に書き込みます。
resource_dns、resource_tcp、resource_ssl、resource_ttfb integer 確実に取得できる場合に書き込むネットワークフェーズの所要時間(ナノ秒単位)。
resource_http_protocol string HTTP プロトコルバージョン。
trace_id、span_id string Trace と RUM の関連付けを有効にした後に書き込みます。
request_header、response_header string プライバシー設定で許可されている場合にのみ書き込む Header スナップショット。
network_instrumentation、network_library string 自動収集エントリポイントと識別されたネットワークライブラリ。

フェーズ所要時間は、resource_timing_source、resource_timing_precision、resource_timing_duration、resource_timing_phase、resource_ttfb_estimated によってソースと精度も記録されます。信頼できるフェーズデータがない場合、SDK は合計所要時間のみを記録します。

Error

フィールド 型 説明
error_type string 自動収集では下の表の標準タイプを使用し、手動 Error ではアプリケーションが渡したタイプを使用します。
error_source string Crash とアプリケーション例外は logger、ネットワークエラーは network、WebView2 ページエラーは webview。
error_situation string run は実行中を示します。次回起動時に復元される Native Crash は startup。
error_message string エラー概要。Crash には例外タイプ、例外コード、アドレスなどの診断情報が含まれます。
error_stack string 完全な例外またはコールスタック。完全な Native コールスタックを取得できない場合は、少なくとも命令アドレスを記録します。

自動収集タイプ

シナリオ error_type error_source 説明
.NET の未処理例外によるプロセス終了 windows_crash logger error_message には完全な例外タイプとメッセージが含まれ、error_stack には Exception.ToString() が含まれます。
未処理の SEH または C++ の std::terminate native_crash logger クラッシュ情報を安全にディスクへ保存し、次回起動時に復元します。例外コード、アドレス、std::terminate 情報は error_message に書き込まれます。
Native UI Watchdog がアプリケーションの無応答を検出 anr_error logger アプリケーションが応答を復帰した後に送信し、継続時間を error_message に書き込みます。
HttpClient リクエストの例外、または自動 Resource が HTTP 4xx/5xx を返した場合 network_error network Error は対応する Resource に関連付けられ、その URL、メソッド、ステータス情報を含みます。
WebView2 の JavaScript Error JavaScript の Error.name。欠落している場合は JavaScriptError webview error_message と error_stack はページの例外から取得されます。
WebView2 の未処理の Promise rejection rejection の name。欠落している場合は UnhandledPromiseRejection webview error_message と error_stack は rejection reason から取得されます。
WebView2 のナビゲーション失敗 WebView2NavigationError webview error_message にはナビゲーション失敗ステータスが含まれます。
WebView2 のプロセス失敗 WebView2ProcessFailed webview error_message にはプロセス失敗のタイプまたは理由が含まれます。

未監視の Task 例外と、WinForms がキャッチした後にアプリケーションの実行を継続させる UI スレッド例外は Crash ではなく、error_type には対応する .NET 例外タイプが使用され、error_source は logger になります。例外の分類と診断の詳細は、error_type、error_message、error_stack に反映されます。

Long Task

フィールド 型 説明
duration integer Long Task の継続時間(ナノ秒単位)。
long_task_stack string 取得できる場合に記録されるコールスタック。
long_task_source string 自動または手動収集のソース。
long_task_delay integer UI スレッドが検出したブロック遅延。
long_task_threshold integer 有効な Long Task のしきい値。
long_task_cooldown integer 連続ブロック報告のクールダウン時間。
long_task_suppressed_count integer クールダウン中にマージされた重複報告の数。

RUM 機能マトリクス

導入方法 View Action Resource Error Long Task
WPF 自動 自動 HttpClient 未処理例外 UI スレッド監視
WinForms 自動 自動 HttpClient 未処理例外 UI スレッド監視
WinUI 3 ウィンドウ関連付け後に自動 自動 HttpClient 未処理例外 UI スレッド監視
Native C/C++ ウィンドウイベントで明示的に接続 メッセージまたはコマンドで明示的に接続 WinHTTP アダプターまたは手動 API クラッシュ復元または手動 API HWND Watchdog または手動 API
WebView2 ページナビゲーション ページインタラクション Fetch/XHR/Resource JavaScript Error renderer Long Task は収集しない
Electron Native Bridge Browser RUM Browser RUM Browser RUM Browser RUM + Main Process イベント Browser RUM。Renderer の無応答は Main Process が送信

Native SDK はプロセスレベルの Detour Hook をインストールしません。アプリケーションは HWND、WinHTTP Handle、またはビジネスライフサイクルイベントを明示的に渡す必要があります。導入方法は桌面 UI 框架およびRUM 手动埋点を参照してください。

Log 機能マトリクス

導入方法 カスタム Log バッチ Log 自動ログソース RUM 関連付け
.NET / C# GuanceSdk.AddLog() GuanceSdk.AddLogs() System.Diagnostics.Trace を収集可能 設定可能
Native C/C++ guance_log_add() guance_log_add_batch() 現時点では Console、ETW、サードパーティ製ログライブラリをインターセプトしない 設定可能
WebView2 Windows ホストが書き込み Windows ホストが書き込み ページの Console を自動ブリッジしない ホストの現在の RUM コンテキストを使用
Electron Native Bridge Browser Logs API Browser Logs Adapter が変換 Console、ページエラー、カスタムスコープは Browser Logs 設定で制御 Native の Session、View、Action コンテキストを使用

Log は独立したキューを使用します。RUM 関連付けを有効にすると、ログ書き込み時の session_id、view_id、action_id が Log とともに送信されます。すでにキューに入った Log は、その後のコンテキスト変更によって変更されません。

Log の主要フィールドは message と status です。同時に service、env、version、SDK、アプリケーション、デバイス、ユーザーフィールドも含まれます。RUM 関連付けを有効にすると、session_id、view_id、action_id とその名前も含まれます。GlobalContext、ユーザー拡張属性、イベントレベルの Properties はカスタムタグとして書き込まれますが、SDK 予約フィールドを上書きすることはできません。

Trace 機能マトリクス

導入方法 自動バウンダリ 手動コンテキスト RUM Resource 関連付け 独立した Span の送信
.NET / C# HttpClient 診断サブスクリプションまたは RumHttpMessageHandler ContextProvider 設定可能 サポート対象外
Native C/C++ guance_rum_winhttp.hpp guance_trace_create_context() またはコールバック 設定可能 サポート対象外
WebView2 ページリクエストは WebView2/Browser 側で処理 ページ SDK が管理 ページ Resource のブリッジ Windows SDK はアップロードしない
Electron Native Bridge Browser RUM SDK Browser RUM SDK Resource は Bridge 経由で Native RUM キューに書き込み サポート対象外

HTTP Trace はリクエスト Header を生成または透過的に渡し、対応する RUM Resource に trace_id、span_id を書き込むことができます。完全な APM Span が必要な場合は、アプリケーションで個別の APM Tracer を使用する必要があります。具体的な形式とターゲットのフィルタリング方法はTrace 配置を参照してください。

データ関連付け

  • 5 種類の RUM データは現在の session_id を共有します。
  • Action、Resource、Error、Long Task は現在の view_id に関連付けられます。
  • Action スコープ内で発生した Resource、Error、Long Task は対応する action_id に関連付けられます。
  • 新しい View が開始されると、前のアクティブな View が終了します。
  • ユーザー情報の更新は後続のデータにのみ影響し、履歴データは変更されません。
  • Log と HTTP Trace の RUM 関連付けは、それぞれの EnableLinkRumData または enable_link_rum_data によって制御されます。

Resource の所要時間

自動 HttpClient Resource はデフォルトで合計所要時間を記録し、所要時間の精度をマークします。HttpResourceTimingProvider または RumResourceTiming.FromPhases() を使用すると、DNS、TCP、TLS、TTFB のフェーズを補完できます。

Native WinHTTP アダプターは、リクエストの開始、終了、ステータス、バイト数、Trace 関連情報を記録します。アプリケーションに信頼できるフェーズ所要時間がない場合、これらのフィールドを推定または偽造してはなりません。

データプライバシー

Resource URL のクエリパラメータ、HTTP Header、Trace ターゲット、Log 属性の処理方法については隐私与权限说明を参照してください。ユーザー、カスタムコンテキスト、手動イベント属性は、書き込み前にアプリケーションでビジネス上のマスキング処理を行う必要があります。

フィードバック

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