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++	デフォルト値	範囲
通常セッションのサンプリング	`SampleRate`	`sample_rate`	`1.0`	`0.0`～`1.0`
Error セッションの追加サンプリング	`SessionErrorSampleRate`	`session_error_sample_rate`	`0.0`	`0.0`～`1.0`

サンプリングの決定は同じセッション内で一貫しています。まず 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 または手動報告

収集の有効化¶

.NET / C#Native C/C++

{{ windows_sdk_name }}Sdk.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`	ロングタスクのしきい値。
`UiThreadProbeInterval`	`250 ms`	UI スレッドのプローブ間隔。
`UiThreadLongTaskCooldown`	`5 s`	連続ブロック報告の集約クールダウン時間。

同じコレクター群が重複登録されることはありませんが、アプリは起動処理内で 1 回だけ呼び出す必要があります。

Native SDK は初期化後、デフォルトでコールドスタートとホットスタートを自動収集し、それぞれ action_type=launch_cold、action_type=launch_hot の Action を生成します。{{ windows_sdk_id }}_sdk_config_init() は enable_app_launch_tracking を 1 に初期化します。自動起動 Action が不要な場合は、{{ windows_sdk_id }}_sdk_init() を呼び出す前に 0 に設定します：

{{ windows_sdk_id }}_sdk_config config;
{{ windows_sdk_id }}_sdk_config_init(&config);
config.enable_app_launch_tracking = 0;

自動収集では、現在のプロセスのトップレベルウィンドウと最初の合成フレームが監視されます。コールドスタート Action には、アプリコード実行前、アプリ初期化、最初のフレームの 3 つのフェーズが含まれます。アプリがバックグラウンドからフォアグラウンドに戻ると、ホットスタート Action が生成されます。アプリは {{ windows_sdk_id }}_rum_add_launch_action() を使用して、ホスト側で測定された起動フェーズを報告することもできます。コールドスタートを手動で報告した場合、SDK は重複する自動コールドスタート Action を生成しません。

トップレベルウィンドウの作成後、UI Watchdog とクラッシュリカバリを有効にできます：

{{ windows_sdk_id }}_sdk_native_monitoring_config monitoring;
{{ windows_sdk_id }}_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 (!{{ windows_sdk_id }}_sdk_enable_native_monitoring(rum, &monitoring)) {
    // HWND または設定が無効です。
}

Native モニタリングパラメーター¶

{{ windows_sdk_id }}_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`	ロングタスクのしきい値。
`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++ アプリでは {{ windows_sdk_id }}_sdk.hpp をインクルードして、ホスト側アダプターが std::terminate ハンドラーを正しくインストールして復元できるようにする必要があります。クラッシュしたプロセスはネットワーク書き込みやキューへの書き込みを実行しません。次回の初期化時に、制限付きのクラッシュエンベロープが RUM Error に変換されます。

ネットワーク Resource¶

.NET / C#Native C/C++

EnableHttpClient = true にすると、URL、メソッド、ステータスコード、合計所要時間、リクエスト/レスポンスサイズ、HTTP プロトコルが自動的に記録されます。明示的な Handler が必要な場合：

using var http = new HttpClient(
    {{ windows_sdk_name }}Sdk.CreateHttpMessageHandler(new HttpClientHandler()));

C++ WinHTTP ではスコープベースのアダプターを使用します：

{{ windows_sdk_id }}::rum::WinHttpResource resource(
    rum,
    request,
    "https://api.example.com/items",
    "GET");
resource.send();
resource.receive();

その他のネットワークライブラリでは、{{ windows_sdk_id }}_rum_start_resource() と {{ windows_sdk_id }}_rum_stop_resource_ext() を呼び出します。Trace Header と RUM の関連付けについては Trace 設定を参照してください。

アプリは実際のネットワークフェーズの所要時間が取得できた場合にのみ、DNS、TCP、TLS、TTFB を記録できます。欠落したフェーズを推定してはなりません。

RUM の手動計装¶

自動収集で業務セマンティクスを表現できない場合は、Action、View、Error、Long Task、Resource を手動で報告できます。.NET / C# では {{ windows_sdk_name }}Sdk を、Native C/C++ では {{ windows_sdk_id }}_rum.h の C ABI を使用します。どちらの接続方法でも同じ Windows RUM データ型が生成されます。

重複収集の回避

手動 API と自動収集は同じセッションに書き込まれます。ウィンドウ、コントロール、HttpClient、WinHTTP、WebView2 によって自動収集されたデータは、手動で再度報告しないでください。

Action¶

自動終了する Action¶

ユーザー操作の収集に使用し、操作中に発生した Resource、Error、Long Task を関連付けます：

.NET / C#Native C/C++

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

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

const char* action_id = {{ windows_sdk_id }}_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 とのペアでの使用が必要です：

.NET / C#Native C/C++

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

ActionId を保存し、業務の終了時に {{ windows_sdk_name }}Sdk.StopAction(actionId) を呼び出すこともできます。

const char* action_id = {{ windows_sdk_id }}_rum_start_action_ext(
    rum,
    "SaveOrder",
    "custom",
    1);

save_order();

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

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

所要時間が既知の Action¶

.NET / C#Native C/C++

{{ windows_sdk_name }}Sdk.AddAction(
    name: "ExportReport",
    type: "custom",
    duration: TimeSpan.FromMilliseconds(320),
    properties: new Dictionary<string, object?>
    {
        ["format"] = "csv"
    });

constexpr int64_t duration_ns = 320LL * 1000 * 1000;
{{ windows_sdk_id }}_rum_add_action(rum, "ExportReport", "custom", duration_ns);

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

View¶

.NET / C#Native C/C++

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

// ページ終了時に実行します。
{{ windows_sdk_name }}Sdk.StopView();

{{ windows_sdk_id }}_rum_start_view(rum, "OrderDetail");

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

新しい View を開始すると、現在アクティブな View は自動的に終了します。View 名は安定したページを表す名前にしてください。注文番号、ユーザー ID、オブジェクトアドレス、検索語句は含めないでください。

Error¶

.NET / C#Native C/C++

try
{
    await LoadOrdersAsync();
}
catch (Exception exception)
{
    {{ windows_sdk_name }}Sdk.AddError(
        exception,
        new Dictionary<string, object?>
        {
            ["operation"] = "load_orders"
        });
}

Exception 以外のエラーは {{ windows_sdk_name }}Sdk.AddError(stack, message, errorType, source) を使用できます。未処理例外の自動収集を有効にしている場合、手動で報告した後も同じ例外をスローし続け、最終的にプロセスが終了すると、windows_crash も 1 件生成されます。業務セマンティクスに応じて重複報告を避けてください。

{{ windows_sdk_id }}_rum_add_error(
    rum,
    "OrderRepository::load_orders",
    "Order request failed",
    "NetworkError",
    "custom");

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

Long Task¶

.NET / C#Native C/C++

{{ windows_sdk_name }}Sdk.AddLongTask(
    duration: TimeSpan.FromMilliseconds(850),
    stack: "ReportRenderer.Render");

constexpr int64_t duration_ns = 850LL * 1000 * 1000;
{{ windows_sdk_id }}_rum_add_long_task(rum, duration_ns, "ReportRenderer::render");

UI スレッドのブロッキング監視を有効にしている場合、同じブロッキングを手動で再度報告しないでください。

Resource¶

.NET / C#Native C/C++

var resourceId = {{ windows_sdk_name }}Sdk.StartResource(
    "https://api.example.com/orders",
    "GET");

{{ windows_sdk_name }}Sdk.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 を使用して、例外が発生した場合や途中で return する場合でも Resource が確実に終了するようにできます：

#include "{{ windows_sdk_id }}_sdk.hpp"

{{ windows_sdk_id }}::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 アプリでは、{{ windows_sdk_id }}_rum_start_resource() と {{ windows_sdk_id }}_rum_stop_resource() をペアで呼び出せます。trace_id、span_id、リクエストサイズ、HTTP プロトコルを書き込む必要がある場合は、{{ windows_sdk_id }}_rum_stop_resource_ext() を使用します。

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

Flush¶

手動イベントはまずローカルキューに入ります。重要なフローの後にすぐに報告を試みる場合は：

.NET / C#Native C/C++

await {{ windows_sdk_name }}Sdk.FlushAsync();

{{ windows_sdk_id }}_sdk_flush(rum);

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

Session Replay¶

試験的機能

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

.NET / C#Native C/C++

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

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

SampleRate と OnErrorSampleRate の範囲はどちらも 0.0～1.0 です。初期化後は録画を手動で制御できます：

{{ windows_sdk_name }}Sdk.StartSessionReplayRecording();
{{ windows_sdk_name }}Sdk.StopSessionReplayRecording();

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

{{ windows_sdk_id }}_sdk_config config;
{{ windows_sdk_id }}_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;

{{ windows_sdk_id }}_sdk_handle rum = {{ windows_sdk_id }}_sdk_init(&config);
{{ windows_sdk_id }}_rum_register_replay_window(
    rum,
    reinterpret_cast<uintptr_t>(main_window));

Native Replay は独立した永続キューと v1/write/rum/replay アップロードチャネルを使用します。{{ windows_sdk_id }}_rum_start_session_replay() と {{ windows_sdk_id }}_rum_stop_session_replay() で録画を手動で制御できますが、開始の呼び出しでも無効化された初期化設定を上書きすることはできません。

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

RUM 設定¶

RUM 初期化設定¶

サンプリング設定¶

収集範囲¶

収集の有効化¶

自動収集パラメーター¶

Native モニタリングパラメーター¶

ネットワーク Resource¶

RUM の手動計装¶

Action¶

自動終了する Action¶

業務の終了を待つ Action¶

所要時間が既知の Action¶

View¶

Error¶

Long Task¶

Resource¶

Flush¶

Session Replay¶

関連ドキュメント¶

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

RUM 設定¶

RUM 初期化設定¶

サンプリング設定¶

収集範囲¶

収集の有効化¶

自動収集パラメーター¶

Native モニタリングパラメーター¶

ネットワーク Resource¶

RUM の手動計装¶

Action¶

自動終了する Action¶

業務の終了を待つ Action¶

所要時間が既知の Action¶

View¶

Error¶

Long Task¶

Resource¶

Flush¶

Session Replay¶

関連ドキュメント¶

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

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