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-adapternpm パッケージのバージョン。
次に 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 属性の処理方法については隐私与权限说明を参照してください。ユーザー、カスタムコンテキスト、手動イベント属性は、書き込み前にアプリケーションでビジネス上のマスキング処理を行う必要があります。