RUM 設定¶
Windows SDK は、C# と Native C/C++ の両方で同じ View、Action、Resource、Error、Long Task を収集します。C# は UI フレームワークの自動収集を提供します。Native は明示的な C ABI と、HWND および WinHTTP 向けのアダプターを使用します。
RUM 初期化設定¶
サンプリング設定¶
| 意味 | .NET / C# | Native C/C++ | デフォルト値 | 範囲と説明 |
|---|---|---|---|---|
| 通常 Session サンプリング | SessionSamplingRate(NuGet 0.1.0-alpha.8 以降) |
session_sampling_rate(vcpkg 0.1.0-alpha.9 以降) |
100 |
0~100 |
| Error Session 追加サンプリング | SessionOnErrorSamplingRate(NuGet 0.1.0-alpha.8 以降) |
session_on_error_sampling_rate(vcpkg 0.1.0-alpha.9 以降) |
0 |
0~100 |
| 通常 Session サンプリング(旧) | SampleRate(非推奨) |
旧構造体 sample_rate(非推奨) |
1 |
0~1。SessionSamplingRate / session_sampling_rate を使用してください。 |
| Error Session 追加サンプリング(旧) | SessionErrorSampleRate(非推奨) |
旧構造体 session_error_sample_rate(非推奨) |
0 |
0~1。SessionOnErrorSamplingRate / session_on_error_sampling_rate を使用してください。 |
新しいフィールドは float のパーセント値で、0.1(0.1% を意味します)のような小数に対応しています。サンプリングの決定は同じ Session 内で一貫しています。まずは 100 を使って導入を検証し、その後データ量に応じて調整することをお勧めします。
同じ .NET 設定オブジェクト内で新旧両方のフィールドが設定されている場合は、明示的に 0 を設定した場合も含めて、新しいフィールドが優先されます。新しいフィールドの値が不正な場合でも、古いフィールドにフォールバックしません。Native は ABI セーフな guance_sdk_config_v2 と guance_sdk_init_v2() を使用します。
収集範囲¶
| 機能 | .NET / C# | Native C/C++ |
|---|---|---|
| View | WPF、WinForms は自動。WinUI 3 は Window を明示的に関連付け | ウィンドウのライフサイクルで View C ABI を呼び出し |
| Action | よく使用される UI コントロールとアプリ起動を自動収集 | アプリ起動を自動収集。業務操作は Action C ABI を呼び出し |
| Resource | HttpClient を自動収集 |
WinHTTP アダプターまたは手動の Resource C ABI |
| Error | 未処理例外を自動収集。手動 Error に対応 | Native クラッシュリカバリまたは手動 Error |
| Long Task | UI スレッドのプローブまたは手動報告 | HWND Watchdog または手動報告 |
収集の有効化¶
GuanceSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
EnableWpf = true,
EnableWinForms = true,
EnableWinUI = true,
EnableWebView = true,
EnableHttpClient = true,
EnableUnhandledException = true,
EnableUiThreadBlock = true,
EnableAppLaunch = true,
UiThreadBlockThreshold = TimeSpan.FromMilliseconds(500),
UiThreadProbeInterval = TimeSpan.FromMilliseconds(250),
UiThreadLongTaskCooldown = TimeSpan.FromSeconds(5)
});
自動収集パラメータ¶
| パラメータ | デフォルト値 | 説明 |
|---|---|---|
EnableWpf |
true |
WPF Window とよく使用されるコントロールを自動収集します。 |
EnableWinForms |
true |
WinForms Form とよく使用されるコントロールを自動収集します。 |
EnableWinUI |
true |
WinUI 3 コントロールの収集を有効にします。Window は引き続き明示的な関連付けが必要です。 |
EnableWebView |
true |
サポートされている WebView2 コントロールを自動検出します。 |
EnableHttpClient |
true |
.NET HTTP 診断イベントを通じて Resource を収集します。 |
EnableUnhandledException |
true |
アプリケーションドメインと UI フレームワークの未処理例外を収集します。 |
EnableUiThreadBlock |
true |
UI スレッドのブロックを監視します。 |
EnableAppLaunch |
true |
アプリ起動フェーズを収集します。 |
UiThreadBlockThreshold |
500 ms |
Long Task のしきい値。 |
UiThreadProbeInterval |
250 ms |
UI スレッドのプローブ間隔。 |
UiThreadLongTaskCooldown |
5 s |
継続的なブロックレポートのマージ用クールダウン時間。 |
同じコレクターセットが重複登録されることはありませんが、アプリは起動フロー内でのみ 1 回呼び出す必要があります。
Native SDK は初期化後、デフォルトでコールドスタートとウォームスタートを自動収集し、それぞれ action_type=launch_cold、action_type=launch_hot の Action を生成します。guance_sdk_config_v2_init() は enable_app_launch_tracking を 1 に初期化します。自動起動 Action が不要な場合は、guance_sdk_init_v2() を呼び出す前に 0 に設定してください:
guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.enable_app_launch_tracking = 0;
| フィールド | デフォルト値 | 説明 |
|---|---|---|
enable_app_launch_tracking |
1 |
コールドスタートとウォームスタートの Action を自動収集します。0 にすると無効になります。 |
自動収集は、現在のプロセスのトップレベルウィンドウと最初の合成フレームを監視します。コールドスタート Action には、アプリコード実行前、アプリ初期化、最初のフレームの 3 つのフェーズが含まれます。アプリがバックグラウンドからフォアグラウンドに戻ると、ウォームスタート Action が生成されます。アプリは guance_rum_add_launch_action() を使用して、ホストが測定した起動フェーズを報告することもできます。コールドスタートを手動で報告した場合、SDK は重複する自動コールドスタート Action を生成しません。
トップレベルウィンドウを作成した後、UI Watchdog とクラッシュリカバリを有効にできます:
guance_sdk_native_monitoring_config monitoring;
guance_sdk_native_monitoring_config_init(&monitoring);
monitoring.enable_ui_hang_monitoring = 1;
monitoring.main_window_handle = reinterpret_cast<uintptr_t>(main_window);
monitoring.enable_native_crash_reporting = 1;
monitoring.enable_minidump = 0;
if (!guance_sdk_enable_native_monitoring(rum, &monitoring)) {
// HWND または設定が無効です。
}
Native 監視パラメータ¶
guance_sdk_native_monitoring_config はバージョン付き構造体です。必ず最初に初期化関数を呼び出す必要があります。
| フィールド | デフォルト値 | 説明 |
|---|---|---|
enable_ui_hang_monitoring |
0 |
HWND UI Watchdog を有効にするかどうか。 |
enable_native_crash_reporting |
0 |
SEH と次回起動時のクラッシュリカバリを有効にするかどうか。 |
main_window_handle |
0 |
現在のプロセスが所有する有効なトップレベル HWND。 |
ui_probe_interval_ms |
250 |
UI プローブ間隔。 |
long_task_threshold_ms |
500 |
Long Task のしきい値。 |
hang_threshold_ms |
5000 |
Application Not Responding のしきい値。 |
hang_report_cooldown_ms |
5000 |
継続的なハングレポートのクールダウン時間。 |
crash_cache_path |
SDK のデフォルトディレクトリ | クラッシュエンベロープとオプションの Dump を保存するローカルディレクトリ。 |
enable_minidump |
0 |
ローカルのミニ Dump を保持するかどうか。Dump は RUM にアップロードされません。 |
max_crash_files |
3 |
クラッシュファイル数の上限。 |
max_crash_file_bytes |
32 MiB |
クラッシュファイルの総バイト数の上限。 |
C++ アプリは guance_sdk.hpp をインクルードして、ホスト側アダプターが std::terminate ハンドラーを正しくインストールおよび復元できるようにする必要があります。クラッシュしたプロセスはネットワークやキューへの書き込みを実行しません。次回の初期化時に、制限付きクラッシュエンベロープが RUM Error に変換されます。
ネットワーク Resource¶
EnableHttpClient = true にすると、URL、メソッド、ステータスコード、合計所要時間、リクエスト/レスポンスサイズ、HTTP プロトコルが自動的に記録されます。明示的な Handler が必要な場合:
C++ WinHTTP はスコープアダプターを使用します:
guance::rum::WinHttpResource resource(
rum,
request,
"https://api.example.com/items",
"GET");
resource.send();
resource.receive();
その他のネットワークライブラリは guance_rum_start_resource() と guance_rum_stop_resource_ext() を呼び出します。Trace Header と RUM の関連付けについては Trace 設定 を参照してください。
アプリは、実際のネットワークフェーズの所要時間を取得できた場合にのみ DNS、TCP、TLS、TTFB を記録し、欠落したフェーズを推定してはなりません。
RUM 手動計装¶
自動収集でビジネスセマンティクスを表現できない場合は、Action、View、Error、Long Task、Resource を手動で報告できます。.NET / C# は GuanceSdk を、Native C/C++ は guance_rum.h の C ABI を使用します。どちらの連携方法でも同じ Windows RUM データ型が生成されます。
重複収集の回避
手動 API と自動収集は同じ Session に書き込まれます。既にウィンドウ、コントロール、HttpClient、WinHTTP、WebView2 によって自動収集されたデータを、再度手動で報告しないでください。
Action¶
自動終了する Action¶
ユーザー操作を収集し、その操作中に発生した Resource、Error、Long Task を関連付けるために使用します:
通常モードは Android SDK と同じ動作です。同時にアクティブな Action は 1 つだけ保持されます。100 ms 以内に StartAction を連続して呼び出すと新しい呼び出しは無視され、100 ms を超えて再度呼び出すと前の Action が終了し、新しい Action が開始されます。Action は View の切り替え時に終了し、最長で約 5 秒間続きます。
ビジネス完了を待つ Action¶
ビジネス操作で非同期ロジックの期間をカバーする必要がある場合は、needWait モードを有効にします。このモードでのみ StopAction とペアで使用する必要があります:
ActionId を保存し、ビジネス処理の終了時に GuanceSdk.StopAction(actionId) を呼び出すこともできます。
needWait Action は明示的に終了するまで新しい Action に置き換えられません。ただし、約 5 秒の最大継続時間と View 切り替えの制限も同様に適用されます。Action の開始時に空の ID が返された場合、その呼び出しは受け入れられなかったことを意味するため、StopAction を呼び出さないでください。
所要時間が既知の Action¶
AddAction は、既に終了し所要時間が既知の独立した Action を直接報告するために使用します。100 ms の高頻度保護や 5 秒の制限を受けず、後続で発生する Resource、Error、Long Task とも関連付けられません。
View¶
新しい View を開始すると、現在アクティブな View が自動的に終了します。View 名は安定したページを表すものにし、注文番号、ユーザー ID、オブジェクトアドレス、検索語句を含めないでください。
Error¶
try
{
await LoadOrdersAsync();
}
catch (Exception exception)
{
GuanceSdk.AddError(
exception,
new Dictionary<string, object?>
{
["operation"] = "load_orders"
});
}
Exception 以外のエラーは GuanceSdk.AddError(stack, message, errorType, source) を使用できます。未処理例外の自動収集を有効にしている場合、手動で報告した後に同じ例外をスローし続け、最終的にプロセスが終了すると、windows_crash も 1 件生成されます。ビジネスセマンティクスに基づいて重複報告を避けてください。
自動収集された .NET の致命的例外は error_type=windows_crash を、Native SEH と C++ の std::terminate は error_type=native_crash を使用します。Crash の error_source はどちらも logger です。Native クラッシュ監視は次回起動時にクラッシュ Error を復元します。クラッシュハンドラー内で手動 Error API を呼び出さないでください。完全な型とフィールドの説明については アプリケーションデータ収集 を参照してください。
Long Task¶
UI スレッドブロック監視が有効な場合は、同じブロック区間を再度手動で報告しないでください。
Resource¶
var resourceId = GuanceSdk.StartResource(
"https://api.example.com/orders",
"GET");
GuanceSdk.StopResource(
resourceId,
statusCode: 200,
timing: RumResourceTiming.FromTotalElapsed(
TimeSpan.FromMilliseconds(120),
source: "manual"),
responseSize: 2048,
requestSize: 0,
resourceType: "http");
アプリが DNS、TCP、TLS、TTFB を測定済みの場合は、RumResourceTiming.FromPhases() を使用してフェーズごとの所要時間を記録できます。信頼できるデータがない場合は、合計所要時間のみを記録してください。
C++ アプリは ResourceScope を使用すると、例外や早期リターンが発生した場合でも Resource を確実に終了できます:
#include "guance_sdk.hpp"
guance::rum::ResourceScope resource(
rum,
"https://api.example.com/orders",
"GET",
"http");
const auto response = send_request();
resource.complete(
response.status_code,
response.body_size,
response.request_size);
純粋な C アプリは guance_rum_start_resource() と guance_rum_stop_resource() をペアで呼び出せます。trace_id、span_id、リクエストサイズ、HTTP プロトコルを書き込む必要がある場合は guance_rum_stop_resource_ext() を使用します。
リクエストが失敗した場合も Resource を終了し、ステータスコードを 0 に設定する必要があります。HttpClient または WinHTTP の自動 Resource を有効にした後は、同じリクエストに対して手動 API を再度呼び出さないでください。
フラッシュ¶
手動イベントは最初にローカルキューに入ります。重要なフロー後にすぐに報告を試みる必要がある場合:
アプリが正常に終了する場合も、ShutdownAsync() または guance_sdk_shutdown() を呼び出す必要があります。HTTP Trace の伝搬とアプリログについては、それぞれ Trace 設定 と Log 設定 を参照してください。
Session Replay¶
NuGet 0.1.0-alpha.9、vcpkg 0.1.0-alpha.10 以降、Replay の実装はオプションコンポーネントによって提供されます。オプションコンポーネントのインストール に従って同じバージョンのコンポーネントを追加してから、以下の設定を有効にしてください。既存の設定、制御、プライバシー API は保持されます。Electron の追加ランタイムのインストール方法は Electron モニタリング を参照してください。
Replay がオフの場合、コンポーネントは読み込まれず、Replay のアップロードチャネルも作成されません。設定がオンでも、コンポーネントが存在しない、バージョンが一致しない、または読み込みに失敗した場合は、SDK は Replay を無効にしてコンポーネントの診断情報を出力します。通常の RUM、Log、Trace は引き続き動作します。コンポーネントをインストールするだけでは録画は開始されません。C# では初期化時に返されるクライアントの IsSessionReplayAvailable を読み取り、Native では guance_rum_is_session_replay_available(rum) を呼び出して、それぞれコンポーネントが利用可能かどうかを判断できます。利用可能な状態は、現在の Session がサンプリング済みであることや録画が開始済みであることを示すものではありません。
Replay パラメータ¶
.NET / C#(SessionReplay) |
Native(sdk_config_v2) |
デフォルト値 | 説明 |
|---|---|---|---|
Enabled |
session_replay_enabled |
false / 0 |
録画を有効にするかどうか。 |
SamplingRate(NuGet 0.1.0-alpha.8 以降) |
session_replay_sampling_rate(vcpkg 0.1.0-alpha.9 以降) |
100 |
通常 Session の Replay サンプリング率(%)。0~100 で、小数も指定できます。 |
OnErrorSamplingRate(NuGet 0.1.0-alpha.8 以降) |
session_replay_on_error_sampling_rate(vcpkg 0.1.0-alpha.9 以降) |
0 |
Error Session の追加サンプリング率(%)。0~100 で、小数も指定できます。 |
TextAndInputPrivacy |
— | MaskAll |
テキストと入力のプライバシーポリシー。 |
TouchPrivacy |
— | Show |
ポインターとタッチ操作のプライバシーポリシー。 |
ImagePrivacy |
— | MaskAll |
画像のプライバシーポリシー。 |
SegmentRecordLimit |
session_replay_segment_record_limit |
500 |
1 つの Replay セグメントのレコード数上限。 |
SegmentBytesLimit |
session_replay_segment_bytes_limit |
1 MiB |
1 つのセグメントの未圧縮バイト数上限。 |
FlushInterval |
— | 5 s |
アクティブなセグメントのフラッシュ間隔。 |
MaxNodeCount |
— | 2000 |
1 回のスナップショットのノード数上限。 |
MaxTreeDepth |
— | 64 |
UI ツリーの深さ上限。 |
MaxTextLength |
— | 256 |
1 ノードのテキスト長の上限。 |
MaxAttributeValueLength |
— | 512 |
1 つの属性値の長さの上限。 |
CaptureImages |
— | true |
false に設定すると画像ポリシーを上書きし、すべての画像を非表示にします。 |
MaxImageBytes |
— | 512 KiB |
画像 1 枚のエンコード後のバイト数上限。 |
MaxImageDimension |
— | 1024 |
画像エンコード時の幅と高さの上限。 |
LargeImagePrivacyThreshold |
— | 100 |
MaskLargeOnly の画像面積しきい値。 |
CustomRenderedTypeNameMarkers |
— | 組み込みのカスタムレンダリング型マーカー | 型名の断片に基づいて、不透明またはカスタムレンダリングされたコンテンツを識別します。 |
SensitiveTextPatterns |
— | メールアドレス、銀行カード番号、電話番号のパターン | 機密テキストを識別するための正規表現のセット。 |
SampleRate(非推奨) |
旧構造体 session_replay_sample_rate(非推奨) |
1 |
旧 0~1 単位と互換性があります。対応する新しいサンプリングフィールドを使用してください。 |
OnErrorSampleRate(非推奨) |
旧構造体 session_replay_on_error_sample_rate(非推奨) |
0 |
旧 0~1 単位と互換性があります。対応する新しいサンプリングフィールドを使用してください。 |
実験的機能
Windows Session Replay はデフォルトで無効になっており、明示的に有効化して検証できます。これは実験的機能です。導入側はリプレイの互換性、プライバシー、パフォーマンス、データ量を自ら評価する必要があり、現在の動作を安定した互換性の約束として扱わないでください。
初期化時に Replay サンプリングとデフォルトのプライバシーポリシーを明示的に有効化して設定します:
GuanceSdk.Init(new GuanceConfig
{
// DatawayUrl / ClientToken / RumAppId ...
SessionReplay = new RumSessionReplayConfig
{
Enabled = true,
SamplingRate = 100, // NuGet 0.1.0-alpha.8 以降対応
OnErrorSamplingRate = 0, // NuGet 0.1.0-alpha.8 以降対応
TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
TouchPrivacy = SessionReplayTouchPrivacy.Show,
ImagePrivacy = SessionReplayImagePrivacy.MaskAll
}
});
SamplingRate と OnErrorSamplingRate(NuGet 0.1.0-alpha.8 以降対応)はどちらも float のパーセント値で、範囲は 0~100 です。初期化後、録画を手動で制御できます:
手動での開始では Enabled = false を回避できません。最初に初期化設定で有効にする必要があります。要素レベルのプライバシー API については Windows セッションリプレイのプライバシーオーバーライド を参照してください。
guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sampling_rate = 100.0f; // vcpkg 0.1.0-alpha.9 以降対応
config.session_replay_on_error_sampling_rate = 0.0f; // vcpkg 0.1.0-alpha.9 以降対応
guance_sdk_handle rum = guance_sdk_init_v2(&config);
if (guance_rum_is_session_replay_available(rum)) {
guance_rum_register_replay_window(
rum,
reinterpret_cast<uintptr_t>(main_window));
guance_rum_start_session_replay(rum);
}
Native Replay は独立した永続キューと v1/write/rum/replay アップロードチャネルを使用します。guance_rum_start_session_replay() と guance_rum_stop_session_replay() で録画を手動制御できますが、開始呼び出しでも、無効になっている初期化設定が上書きされることはありません。
WebView2 と Electron のページ record は、ネイティブ Bridge を通じて同じネイティブ Session、セグメント、キュー、アップロードチャネルに入ります。それぞれ WebView2 モニタリング と Electron モニタリング を参照してください。