Windows アプリケーション導入¶

Windows SDK は、.NET/C# および Native C/C++ に対して、統一されたリアルユーザーモニタリング（RUM）、ログ、HTTP トレースの関連付け機能を提供します。アプリケーションは実行時に導入方法を選択し、データは同一のアプリケーション ID、サービス、環境でコンソールに取り込まれます。

読み進め方¶

初回導入：まずクイックスタートをご覧ください。
完全な導入：引き続き本ドキュメントをお読みください。
パラメータ詳細：SDK 初期化、RUM 設定、ログ設定、トレース設定を参照してください。
高度な機能：「高度なシナリオ」グループの専用ページをご覧ください。
問題のトラブルシューティング：トラブルシューティングを参照してください。

前提条件¶

サポート範囲¶

項目	サポート範囲
オペレーティングシステム	Windows 10+
.NET ターゲットフレームワーク	`net6.0` / `net8.0`
Native 標準	C11 ABI、C++17 アダプター
NuGet Native RID	`win-x64` / `win-x86` / `win-arm64`
vcpkg Native	動的 `x64-windows`、UWP 非対応
配布方法	NuGet / vcpkg
データレポート	パブリック DataWay、ローカル環境デプロイ（Datakit）
RUM	View、Action、Resource、Error、Long Task
ログ	カスタム/バッチログ、独立キュー、RUM 関連付け；C# は `System.Diagnostics.Trace` 収集に対応
トレース	HTTP ヘッダー伝搬と RUM Resource 関連付け、独立した APM スパンはアップロードしない
セッションリプレイ	デフォルトで無効；WPF、WinForms、WinUI 3、WebView2、Electron、Native いずれも明示的に有効化して検証可能、現時点では実験的機能

機能の制限

セッションリプレイは明示的に有効化して検証できますが、依然として実験的機能であり、安定した互換性の保証対象ではありません。Avalonia、.NET MAUI、UWP には独立した自動収集アダプターはありません。Native C ABI を再利用するフレームワークでは、ウィンドウとコントロールのライフサイクルを自行管理する必要があります。

アプリケーション導入¶

導入方法の選択¶

導入方法	対応アプリケーション	インストール方法	UI 境界
.NET / C#	WPF、WinForms、WinUI 3	`Guance.Windows` NuGet	フレームワークによる自動収集；WinUI 3 は Window を明示的に関連付け
Native C/C++	Win32、`HWND` ベースのデスクトップフレームワーク	CMake、ヘッダーファイル、インポートライブラリ、`guance_windows_native.dll`	ウィンドウとコントロールのライフサイクルを C ABI で明示的に呼び出し
WebView2	.NET ホスト内の Edge WebView2	.NET SDK に同梱	自動検出またはコントロールの明示的な関連付け
Electron	Electron Renderer + Windows Native Bridge	Browser SDK + `guance-windows-native[electron-bridge]`	Browser SDK は収集とシリアライズのみを担当；信頼された Main Process とネイティブ側がセッション、キュー、アップロードを管理

アプリケーションの作成¶

Guance コンソールにログインし、「ユーザーアクセスモニタリング」から「アプリケーションを作成」をクリックします：

アプリケーション名とアプリケーション ID を入力します。
アプリケーションタイプは「カスタム」を選択します。
アプリケーション ID を保存します。RumAppId または rum_app_id で使用します。

同一 Windows 製品の C#、C++、WebView2、Electron で同じアプリケーション ID を使用し、service、version、ランタイムタグでデータを区別できます。

インストール¶

.NET / C#Native C/C++Electron

dotnet add package Guance.Windows --version [latest_version]

サンプル：

GuanceCloud vcpkg レジストリ経由での guance-windows-native インストールを推奨します。レジストリ、マニフェスト、CMake の設定はクイックスタートに従って完了してください。インストール後、公開されている CMake Target をリンクします：

find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)

SDK のソースコードをデバッグする場合は、直接ビルドすることも可能です：

git clone https://github.com/GuanceCloud/datakit-windows-desktop.git
cd datakit-windows-desktop
cmake -S src/Guance.Windows.Native -B build/native -A x64
cmake --build build/native --config Release

公開ヘッダーファイル：

guance_rum.h：C11 ABI、C および C++ で使用可能；
guance_sdk.hpp：C++ スコープ Resource と std::terminate アダプター；
guance_rum_winhttp.hpp：同期および非同期 WinHTTP Resource/Trace アダプター。

アプリケーション、インポートライブラリ、DLL のアーキテクチャは一致している必要があります。現在の vcpkg ポートは動的 x64-windows のみを提供します。NuGet パッケージ内の x86、x64、ARM64 Native DLL は .NET ラッパー層で使用するものであり、C/C++ ヘッダーファイルとインポートライブラリは含まれません。

Renderer に Browser SDK をインストールします：

npm install @cloudcare/browser-rum @cloudcare/browser-logs

Electron フルモードでは、まずクイックスタートに従って GuanceCloud vcpkg レジストリを設定し、vcpkg.json 内で guance-windows-native の electron-bridge Feature を有効化した上で、マニフェストモードで vcpkg install --triplet x64-windows を実行する必要があります。この Feature により Bridge EXE と対応する Native DLL がインストールされます。両者は一緒にパッケージ化する必要があります。

C++ 初期化のハイブリッドモードでは Bridge EXE は起動されず、C++ ホストが既存の SDK ハンドルに書き込むアダプターを提供します。完全なインストール、パッケージ化、機能の制限についてはElectron モニタリングを参照してください。

ソースコード：GuanceCloud/datakit-windows-desktop

初期化の説明¶

レポート方法¶

パブリック DataWayローカル環境デプロイ（Datakit）

ランタイム	アドレス	認証情報
.NET / C#	`GuanceConfig.DatawayUrl`	`GuanceConfig.ClientToken`
Native C/C++	`guance_sdk_config.dataway_url`	`guance_sdk_config.client_token`

ランタイム	アドレス	認証情報
.NET / C#	`GuanceConfig.DatakitUrl`	Client Token 不要
Native C/C++	`guance_sdk_config.datakit_url`	Client Token 不要

ローカル環境デプロイを使用する前に、DataKit をインストールし、RUM 収集器を有効化する必要があります。

初期化の順序¶

.NET / C#Native C/C++

// config には少なくともレポートアドレスと RUM アプリケーション情報を含めます。ログ/トレースは必要に応じて追加します。
GuanceSdk.Init(config);
GuanceSdk.EnableAutomaticInstrumentation();

// アプリケーション終了前に実行します。
await GuanceSdk.ShutdownAsync();

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_start_view(rum, "MainWindow");

// メッセージループ終了後に実行します。
guance_rum_stop_view(rum);
guance_sdk_shutdown(rum);

ログまたはトレースが必要な場合は、guance_sdk_init() 成功後にそれぞれ guance_log_configure()、guance_trace_configure() を呼び出します。

SDK はディスクキューを使用して RUM とログをキャッシュします。正常終了時にシャットダウンプロセスを完了させ、プロセス終了時に未永続化の操作が残らないようにしてください。

詳細設定の参照先¶

ベースアドレス、認証、キュー、ライフサイクル：SDK 初期化
View、Action、Resource、Error、Long Task：RUM 設定
カスタムログと自動トレース出力：ログ設定
HTTP トレースヘッダーと RUM の関連付け：トレース設定

高度なシナリオ¶

WPF、WinForms、WinUI 3、Native UI：デスクトップ UI フレームワーク
WebView2 ページモニタリング：WebView2 モニタリング
Electron Renderer と Native Bridge：Electron モニタリング
プライバシー、権限、データマスキング：プライバシーと権限の説明

よくある質問¶

初期化、データレポート、デスクトップ UI、WebView2、Electron、ログ、トレース、セッションリプレイに関する問題はトラブルシューティングを参照してください。