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 はリクエストヘッダーを生成または透過的に転送し、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 属性の処理方法については、プライバシーと権限の説明を参照してください。ユーザー、カスタムコンテキスト、手動イベントの属性については、アプリケーションが書き込み前に業務上のマスキング処理を行う必要があります。