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 のバージョン。Electron Adapter は、アプリとともに配布される Native SDK バージョンを渡す必要があり、業務アプリケーションのバージョンで代用することはできません。
`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 の予約フィールドを上書きすることはできません。

その他のデータ型の属性¶

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 を生成または透過的に転送し、trace_id、span_id を対応する RUM Resource に書き込むことができます。完全な 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 属性の処理方法は、プライバシーと権限の説明を参照してください。ユーザー、カスタムコンテキスト、手動イベントの属性は、アプリケーションが書き込み前に業務上のマスキングを実施する必要があります。