コンテンツにスキップ

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

Windows SDK は .NET/C# と Native C/C++ に、RUM、Log、HTTP Trace の統合された関連付け機能を提供します。アプリケーションはランタイムに応じて導入方法を選択し、データは同じアプリケーション ID、サービス、環境ディメンションを使用してコンソールに送信されます。

参照の流れ

前提条件

サポート範囲

項目 サポート範囲
オペレーティングシステム 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」に移動して「アプリケーションの作成」をクリックします:

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

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

導入方法の選択

アプリケーション設定ページで「Agent 自動導入」または「手動導入」を選択し、「導入設定」を完了します。既存のアプリケーションは設定ページに直接移動して導入を続行できます。

導入方法 ユースケース 操作入口
Agent 自動導入 コーディングアシスタントにプロジェクトを分析させ、SDK の導入を完了させたい場合 コンソールで生成されたプロンプトをコピーし、アプリケーションのコードリポジトリでコーディングアシスタントに渡して実行します
手動導入 SDK を自身でインストールし、パラメータを設定したい場合 データ送信方法を確認し、本文とクイックスタートに従って設定を完了します

Agent 自動導入

  1. 現在のアプリケーションの設定ページで「Agent 自動導入」を選択します。
  2. 「導入設定」内の完全なプロンプトをコピーし、現在のアプリケーションの導入情報が使用されていることを確認します。
  3. アプリケーションのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付け、Agent が導入ガイドに従ってプロジェクトを分析し SDK 設定を完了します。
  4. アプリケーションをビルドして実行し、ページアクセスなどの操作をトリガーした後、現在のアプリケーションのエクスプローラーでデータを受信したことを確認します。

ページに個人用 API Key または一時認可コードが準備できていない旨が表示された場合は、指示に従って補完してからプロンプトを再度コピーしてください。

手動導入

アプリケーション設定ページで「手動導入」を選択し、データ送信方法を確認します:

  • パブリック DataWay:現在のアプリケーションの導入設定から送信先アドレスと Client Token を取得します。DataKit を自身でデプロイする必要はありません。
  • ローカル環境デプロイ:デプロイ済みの DataKit を使用してデータを受信し、アプリケーションがその送信先アドレスにアクセスできることを確認します。

以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了してください。既存の SDK 設定がある場合は、先に確認して再利用し、重複した初期化を避けてください。

インストール

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

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 をインストールします:

npm install @cloudcare/electron-native-adapter@alpha @cloudcare/browser-rum @cloudcare/browser-logs

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 コレクターを有効にする必要があります。

初期化の順序

// config には少なくとも送信先アドレスと RUM アプリケーション情報を含めます。Log/Trace は必要に応じて追加します。
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);

Log または Trace が必要な場合は、guance_sdk_init() の成功後にそれぞれ guance_log_configure()、guance_trace_configure() を呼び出します。

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

詳細設定への入口

  • 基本アドレス、識別情報、キュー、ライフサイクル:SDK の初期化
  • View、Action、Resource、Error、Long Task:RUM 設定
  • カスタムログと自動 Trace 出力:Log 設定
  • HTTP Trace Header と RUM の関連付け:Trace 設定

高度なシナリオ

よくある質問

初期化、データ送信、デスクトップ UI、WebView2、Electron、Log、Trace、Session Replay の問題については、トラブルシューティングを参照してください。

フィードバック

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