コンテンツにスキップ

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 サンプリング SampleRate sample_rate 1.0 0.01.0
Error Session 追加サンプリング SessionErrorSampleRate session_error_sample_rate 0.0 0.01.0

サンプリングの決定は、同一 Session 内で一貫されます。まずは 1.0 で接続を検証し、データ量に応じて調整することをお勧めします。

収集範囲

機能 .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_coldaction_type=launch_hot の Action を生成します。guance_sdk_config_init()enable_app_launch_tracking1 に初期化します。自動起動 Action が不要な場合は、guance_sdk_init() を呼び出す前に 0 に設定してください。

guance_sdk_config config;
guance_sdk_config_init(&config);
config.enable_app_launch_tracking = 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 が必要な場合:

using var http = new HttpClient(
    GuanceSdk.CreateHttpMessageHandler(new HttpClientHandler()));

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 を関連付けるために使用します。

var action = GuanceSdk.StartAction("SaveOrder", "click");
if (!action.IsAccepted)
{
    // この呼び出しは高頻度保護により無視されました。
}

通常モードでは StopAction を呼び出す必要はありません。返された RumActionScope を解放しても Action は終了しません。

const char* action_id = guance_rum_start_action(rum, "SaveOrder", "click");
if (action_id[0] == '\0') {
    // この呼び出しは高頻度保護により無視されました。
}

通常モードは Android SDK と同様の動作をします。同時に保持されるアクティブな Action は1つのみです。100 ms 以内に StartAction を連続して呼び出すと、新しい呼び出しは無視されます。100 ms を超えてから再度呼び出すと、前の Action が終了し、新しい Action が開始されます。Action は View の切り替え時に終了し、最大約5秒間持続します。

ビジネス終了を待機する Action

ビジネス操作が非同期ロジックをカバーする必要がある場合は、needWait モードを有効にします。このモードでのみ StopAction と組み合わせて使用する必要があります。

using (GuanceSdk.StartAction("SaveOrder", "custom", needWait: true))
{
    await SaveOrderAsync();
}

また、ActionId を保存し、ビジネス終了時に GuanceSdk.StopAction(actionId) を呼び出すこともできます。

const char* action_id = guance_rum_start_action_ext(
    rum,
    "SaveOrder",
    "custom",
    1);

save_order();

if (action_id[0] != '\0') {
    guance_rum_stop_action(rum, action_id);
}

needWait Action は、明示的に終了されるまで新しい Action に置き換えられませんが、約5秒の最大持続時間と View 切り替えの制限を受けます。Action 開始時に空の ID が返された場合、この呼び出しが受け入れられなかったことを示すため、StopAction を呼び出さないでください。

所要時間既知の Action

GuanceSdk.AddAction(
    name: "ExportReport",
    type: "custom",
    duration: TimeSpan.FromMilliseconds(320),
    properties: new Dictionary<string, object?>
    {
        ["format"] = "csv"
    });
constexpr int64_t duration_ns = 320LL * 1000 * 1000;
guance_rum_add_action(rum, "ExportReport", "custom", duration_ns);

AddAction は、既に終了しており所要時間が既知の独立した Action を直接報告するために使用します。100 ms の高頻度保護や5秒の制限を受けず、後続の Resource、Error、Long Task も関連付けられません。

View

GuanceSdk.StartView(
    "OrderDetail",
    new Dictionary<string, object?>
    {
        ["order_type"] = "subscription"
    });

// ページ終了時に実行します。
GuanceSdk.StopView();
guance_rum_start_view(rum, "OrderDetail");

// ページまたはウィンドウ終了時に実行します。
guance_rum_stop_view(rum);

新しい 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 が追加で生成されます。ビジネスロジックに基づいて重複報告を避けてください。

guance_rum_add_error(
    rum,
    "OrderRepository::load_orders",
    "Order request failed",
    "NetworkError",
    "custom");

自動収集された .NET 致命的例外は error_type=windows_crash を、Native SEH と C++ std::terminateerror_type=native_crash を使用します。Crash の error_source は常に logger です。Native クラッシュ監視は次回起動時にクラッシュ Error を復元します。クラッシュハンドラ内で手動 Error API を呼び出さないでください。完全な型とフィールドの説明については、アプリケーションデータ収集を参照してください。

Long Task

GuanceSdk.AddLongTask(
    duration: TimeSpan.FromMilliseconds(850),
    stack: "ReportRenderer.Render");
constexpr int64_t duration_ns = 850LL * 1000 * 1000;
guance_rum_add_long_task(rum, duration_ns, "ReportRenderer::render");

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_idspan_id、リクエストサイズ、HTTP プロトコルを書き込む必要がある場合は、guance_rum_stop_resource_ext() を使用します。

リクエストが失敗した場合でも Resource を終了し、ステータスコードを 0 に設定する必要があります。HttpClient または WinHTTP の自動 Resource を有効にした後は、同じリクエストに対して手動 API を再度呼び出さないでください。

Flush

手動イベントは最初にローカルキューに入ります。重要なフローの後にすぐにアップロードを試行する必要がある場合:

await GuanceSdk.FlushAsync();
guance_sdk_flush(rum);

アプリケーションが正常に終了する場合でも、ShutdownAsync() または guance_sdk_shutdown() を呼び出す必要があります。HTTP Trace 伝播とアプリケーションログについては、それぞれ Trace 設定Log 設定 を参照してください。

Session Replay

実験的機能

Windows Session Replay はデフォルトで無効になっています。明示的に有効にして検証することはできますが、まだ安定版リリースの範囲には含まれていません。導入側は、リプレイの互換性、プライバシー、パフォーマンス、データ量を自己評価する必要があり、現在の動作を安定した互換性の保証と見なすべきではありません。

初期化時に明示的に有効にし、Replay サンプリングとデフォルトのプライバシーポリシーを設定します。

GuanceSdk.Init(new GuanceConfig
{
    // DatawayUrl / ClientToken / RumAppId ...
    SessionReplay = new RumSessionReplayConfig
    {
        Enabled = true,
        SampleRate = 1.0,
        OnErrorSampleRate = 0.0,
        TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
        TouchPrivacy = SessionReplayTouchPrivacy.Show,
        ImagePrivacy = SessionReplayImagePrivacy.MaskAll
    }
});

SampleRateOnErrorSampleRate の範囲はともに 0.01.0 です。初期化後、手動で録画を制御できます。

GuanceSdk.StartSessionReplayRecording();
GuanceSdk.StopSessionReplayRecording();

手動での開始は Enabled = false を無効化できません。最初に初期化設定で有効にする必要があります。要素レベルのプライバシー API については、Windows セッションリプレイプライバシーオーバーライド を参照してください。

guance_sdk_config config;
guance_sdk_config_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sample_rate = 1.0;
config.session_replay_on_error_sample_rate = 0.0;

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_register_replay_window(
    rum,
    reinterpret_cast<uintptr_t>(main_window));

Native Replay は独立した永続化キューと v1/write/rum/replay アップロードチャネルを使用します。guance_rum_start_session_replay()guance_rum_stop_session_replay() で手動で録画を制御できますが、開始呼び出しは無効になっている初期化設定を上書きしません。

WebView2 と Electron のページ record は、ネイティブ Bridge を介して同一のネイティブ Session、セグメント、キュー、アップロードチャネルに入ります。それぞれ WebView2 監視Electron 監視 を参照してください。

関連ドキュメント

フィードバック

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