Windows アプリケーションの導入¶
Windows SDK は .NET/C# と Native C/C++ に、RUM、Log、HTTP Trace の統合された関連付け機能を提供します。アプリケーションはランタイムに応じて導入方法を選択し、データは同じアプリケーション ID、サービス、環境ディメンションを使用してコンソールに送信されます。
参照の流れ¶
- 初回導入:まず導入方法を選択します。手動導入の場合はクイックスタートを参照してください。
- 完全な導入:引き続き本文をお読みください。
- パラメータの詳細:SDK の初期化、RUM 設定、Log 設定、Trace 設定を参照してください。
- 高度な機能:「高度なシナリオ」グループの専用ページを参照してください。
- 問題の調査:トラブルシューティングを参照してください。
前提条件¶
サポート範囲¶
| 項目 | サポート範囲 |
|---|---|
| オペレーティングシステム | Windows 10+ |
| .NET ターゲットフレームワーク | net6.0 / net8.0 |
| Native 標準 | C11 ABI、C++17 アダプター |
| NuGet Native RIDs | win-x64 / win-x86 / win-arm64 |
| vcpkg Native | 動的 x64-windows、UWP 以外 |
| 配布方法 | NuGet / vcpkg |
| データ送信 | パブリック DataWay、ローカル環境デプロイ(Datakit) |
| RUM | View、Action、Resource、Error、Long Task |
| Log | カスタム/バッチ Log、独立キュー、RUM の関連付け。C# は System.Diagnostics.Trace の収集をサポート |
| Trace | HTTP Header の伝播と RUM Resource の関連付け。独立した APM Span はアップロードしません |
| Session Replay | デフォルトでは無効です。対応するオプションコンポーネントをインストールした後に明示的に有効化する必要があります。WPF、WinForms、WinUI 3、WebView2、Electron、Native をサポートしますが、現在は実験的機能です |
機能の境界
Session Replay は明示的に有効化して検証できますが、引き続き実験的機能であり、安定した互換性を保証するものではありません。Avalonia、.NET MAUI、UWP には独立した自動収集アダプターがありません。Native C ABI を再利用できるフレームワークでは、ウィンドウとコントロールのライフサイクルを自身で管理する必要があります。
アプリケーションの導入¶
SDK とランタイムの選択¶
| SDK とランタイム | 対象アプリケーション | インストール方法 | 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 とネイティブ側が Session、キュー、アップロードを管理 |
アプリケーションの作成¶
Guance コンソールにログインし、「RUM」に移動して「アプリケーションの作成」をクリックします:
- アプリケーション名とアプリケーション ID を入力します。
- アプリケーションタイプで「カスタム」を選択します。
- アプリケーション ID を保存し、
RumAppIdまたはrum_app_idで使用します。
同じ Windows 製品の C#、C++、WebView2、Electron は同じアプリケーション ID を使用でき、service、version、ランタイムタグによってデータを区別できます。
導入方法の選択¶
アプリケーション設定ページで「Agent 自動導入」または「手動導入」を選択し、「導入設定」を完了します。既存のアプリケーションは設定ページに直接移動して導入を続行できます。
| 導入方法 | ユースケース | 操作入口 |
|---|---|---|
| Agent 自動導入 | コーディングアシスタントにプロジェクトを分析させ、SDK の導入を完了させたい場合 | コンソールで生成されたプロンプトをコピーし、アプリケーションのコードリポジトリでコーディングアシスタントに渡して実行します |
| 手動導入 | SDK を自身でインストールし、パラメータを設定したい場合 | データ送信方法を確認し、本文とクイックスタートに従って設定を完了します |
Agent 自動導入¶
- 現在のアプリケーションの設定ページで「Agent 自動導入」を選択します。
- 「導入設定」内の完全なプロンプトをコピーし、現在のアプリケーションの導入情報が使用されていることを確認します。
- アプリケーションのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付け、Agent が導入ガイドに従ってプロジェクトを分析し SDK 設定を完了します。
- アプリケーションをビルドして実行し、ページアクセスなどの操作をトリガーした後、現在のアプリケーションのエクスプローラーでデータを受信したことを確認します。
ページに個人用 API Key または一時認可コードが準備できていない旨が表示された場合は、指示に従って補完してからプロンプトを再度コピーしてください。
手動導入¶
アプリケーション設定ページで「手動導入」を選択し、データ送信方法を確認します:
- パブリック DataWay:現在のアプリケーションの導入設定から送信先アドレスと Client Token を取得します。DataKit を自身でデプロイする必要はありません。
- ローカル環境デプロイ:デプロイ済みの DataKit を使用してデータを受信し、アプリケーションがその送信先アドレスにアクセスできることを確認します。
以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了してください。既存の SDK 設定がある場合は、先に確認して再利用し、重複した初期化を避けてください。
インストール¶
Session Replay を使用する場合は、同じバージョンの Guance.Windows.SessionReplay を追加します。インストールと移行の要件についてはオプションコンポーネントのインストールを参照してください。
例:
SDK の 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++ のヘッダーファイルとインポートライブラリは含まれません。Session Replay は同じ port の replay Feature を介してインストールします。
Main Process Adapter と Renderer Browser SDK をインストールします:
Electron のフルモードでは、npm Adapter が基本ランタイムをダウンロードし、Bridge EXE を管理します。Replay を使用する場合は、同じバージョン、同じアーキテクチャの Replay 補足アーカイブを明示的にインストールし、基本ランタイムと一緒に ASAR の外にパッケージ化する必要があります。
C++ で初期化するハイブリッドモードでは、ホストが named-pipe Bridge Server を起動し、Electron Adapter が既存の SDK Handle に接続します。Replay コンポーネントはホストの vcpkg replay Feature によって提供されます。完全なインストール、パッケージ化、機能の境界については Electron モニタリングを参照してください。
ソースコード:Windows SDK ソースコード
初期化の説明¶
データ送信方法¶
| ランタイム | アドレス | 認証情報 |
|---|---|---|
| .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 コレクターを有効にする必要があります。
初期化の順序¶
SDK はディスクキューを使用して RUM と Log をキャッシュします。正常終了時にはシャットダウンフローを完了し、プロセス終了時に未永続化の操作が残らないようにしてください。
詳細設定への入口¶
- 基本アドレス、識別情報、キュー、ライフサイクル:SDK の初期化
- View、Action、Resource、Error、Long Task:RUM 設定
- カスタムログと自動 Trace 出力:Log 設定
- HTTP Trace Header と RUM の関連付け:Trace 設定
高度なシナリオ¶
- WPF、WinForms、WinUI 3、Native UI:デスクトップ UI フレームワーク
- WebView2 ページモニタリング:WebView2 モニタリング
- Electron Renderer と Native Bridge:Electron モニタリング
- プライバシー、権限、データマスキング:プライバシーと権限の説明
よくある質問¶
初期化、データ送信、デスクトップ UI、WebView2、Electron、Log、Trace、Session Replay の問題については、トラブルシューティングを参照してください。