クイックスタート¶
Windows SDK は 2 つの独立した配布チャネルを提供します。.NET/C# アプリケーションは NuGet 経由で Guance.Windows およびオプションコンポーネントを使用し、Native C/C++ アプリケーションは SDK の vcpkg レジストリ経由で guance-windows-native およびオプションの Feature を使用します。両者は同じ RUM アプリケーション ID とデータ送信方式を使用しますが、パッケージのバージョン、アップグレードのタイミング、変更履歴はそれぞれ独立しています。
アプリケーションは Agent による自動接続と手動接続に対応しています。以下の手順では、手動接続の最小構成について説明します。
前提条件¶
- 「RUM」で「カスタム」アプリケーションを作成し、アプリケーション ID を取得します。
- データ送信方式を 1 つ用意します。
- パブリック DataWay:送信先アドレスと Client Token
- ローカル環境デプロイ(DataKit):アプリケーションプロセスからアクセス可能な DataKit アドレス
- アプリケーションが Windows 10 以降で動作していることを確認します。
接続手順¶
- アプリケーションの技術スタックに応じて、NuGet または vcpkg パッケージを選択します。
- 依存関係をインストールし、RUM アプリケーションと送信設定を入力します。
- SDK を初期化し、必要に応じて自動収集、Log、Trace、Session Replay を有効にします。
- アプリケーションを実行し、コンソールでデータ送信の成功を確認します。
パッケージの選択¶
| アプリケーション種別 | パッケージ | インストール方法 | 現在のサポート |
|---|---|---|---|
| .NET / C# | Guance.Windows |
NuGet.org | net6.0、net8.0、net6.0-windows10.0.17763.0、net8.0-windows10.0.17763.0;x86、x64、ARM64 の Native ランタイムアセット |
| Native C/C++ | guance-windows-native |
SDK vcpkg レジストリ | Windows x64、UWP 以外;最初のバージョンは動的ライブラリ |
バージョン情報
本記事では [latest_version] で最新バージョンを表します。NuGet の検索画面ではプレリリースパッケージを有効にする必要があります。本番プロジェクトでは、[latest_version] を検証済みの具体的なバージョンに置き換え、依存関係を固定してください。
.NET / C#:NuGet の使用¶
プロジェクトディレクトリでインストールします:
またはプロジェクトファイルに追加します:
NuGet パッケージはランタイム識別子(RID)に応じて以下の Native DLL を組み込むため、手動でコピーする必要はありません:
runtimes/win-x64/native/guance_windows_native.dll
runtimes/win-arm64/native/guance_windows_native.dll
runtimes/win-x86/native/guance_windows_native.dll
Native C/C++:vcpkg の使用¶
SDK レジストリの設定¶
プロジェクトのルートディレクトリで vcpkg-configuration.json を作成または更新します。デフォルトレジストリのベースラインは、プロジェクトで検証済みの Microsoft vcpkg コミットに置き換えてください。<latest-sdk-vcpkg-registry-commit> は SDK レジストリの最新コミットを表します。接続時にはプレースホルダーを実際のコミットに置き換えて固定し、ビルドの再現性を確保してください。
{
"default-registry": {
"kind": "git",
"repository": "https://github.com/microsoft/vcpkg",
"baseline": "<compatible-microsoft-vcpkg-commit>"
},
"registries": [
{
"kind": "git",
"repository": "https://github.com/GuanceCloud/gc-vcpkg-registry.git",
"baseline": "<latest-sdk-vcpkg-registry-commit>",
"packages": [
"guance-windows-native"
]
}
]
}
依存関係の宣言とインストール¶
プロジェクトのルートディレクトリにある vcpkg.json でポートを宣言します:
その後、マニフェストモードでインストールします:
CMake のリンク¶
CMake の設定時に vcpkg の toolchain ファイルを渡し、CMakeLists.txt でパッケージを検索してリンクします:
find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)
C ヘッダーファイル guance_sdk.h、各シグナル専用の C ヘッダーファイル guance_rum.h、guance_trace.h、guance_log.h、または C++ 補助ヘッダーファイル guance_sdk.hpp を使用できます。完全な C API については、公開されている guance_sdk.h を参照してください。
オプションコンポーネントのインストール¶
NuGet 0.1.0-alpha.9 および vcpkg 0.1.0-alpha.10 以降、Session Replay はオプションコンポーネントとして提供されます。RUM、Log、Trace のみを使用する場合は、基本パッケージをインストールするだけで済みます。既存の Replay アプリケーションを分割パッケージ版にアップグレードする場合は、Replay コンポーネントを追加でインストールする必要がありますが、既存の設定と制御呼び出しはそのまま維持されます。
| 機能 | .NET / C# | Native C/C++ |
|---|---|---|
| Session Replay | Guance.Windows.SessionReplay |
同一 port の replay Feature、guance_windows_replay.dll をインストール |
.NET で Replay を使用する場合は以下のコンポーネントを追加し、[latest_version] を基本パッケージと同じ NuGet バージョンに固定します:
Replay NuGet パッケージは同一バージョンの基本パッケージに正確に依存します。マネージド Replay パッケージには Native Replay DLL は含まれません。Native アプリケーションでは replay Feature を選択します:
インストール後、Native Replay DLL は同一バージョン・同一アーキテクチャの guance_windows_native.dll と同じディレクトリに配置する必要があります。コンポーネントをインストールしても Replay は自動的に有効にならないため、有効化と録画開始を設定する必要があります。詳しくは RUM 設定を参照してください。
Electron Full Mode では npm Adapter がビルド段階で Replay 補助ランタイムをインストールし、Mixed Mode では Native ホストが replay Feature をインストールします。詳しくは Electron モニタリングを参照してください。
最小初期化の例¶
初期化時には、RUM アプリケーション ID、サービス名、環境、アプリケーションバージョンを必ず入力してください。パブリック DataWay モードでは DatawayUrl と ClientToken を使用します。ローカル環境デプロイ(DataKit)を使用する場合は DatakitUrl のみを設定すればよく、パブリック Token は不要です。
#include "guance_sdk.h"
guance_sdk_config_v2 config; // vcpkg 0.1.0-alpha.9 以降でサポート
guance_sdk_config_v2_init(&config);
config.dataway_url = "https://openway.<your-domain>";
config.client_token = "<client-token>";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "prod";
config.application_version = "1.0.0";
guance_sdk_handle sdk = guance_sdk_init_v2(&config);
if (sdk == nullptr) {
// 初期化失敗を処理します。
}
#include "guance_sdk.h"
guance_sdk_config_v2 config; // vcpkg 0.1.0-alpha.9 以降でサポート
guance_sdk_config_v2_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "local";
config.application_version = "1.0.0";
guance_sdk_handle sdk = guance_sdk_init_v2(&config);
一度初期化した後、アプリケーション終了前に明示的にキューをフラッシュし、SDK をシャットダウンします:
オプション:Log、Trace、Session Replay の初期化¶
- .NET/C# では、WPF、WinForms、WinUI 3、
HttpClient、未処理例外、UI スレッドのブロックを自動収集するか選択できます。最初のウィンドウを作成する前にGuanceSdk.EnableAutomaticInstrumentation()を呼び出してください。Native C/C++ では、公開 C API を通じてウィンドウ、コマンド、ネットワークの境界に明示的に組み込みます。 - Trace Header は信頼できるサービスにのみ送信してください。Trace 設定の送信先アドレスホワイトリストを使用して、Header を注入できるリクエストを制限してください。
- SDK はデフォルトでプライバシー保護設定を使用します。Session Replay はデフォルトで無効であり、明示的に有効化する必要があります。また、実験的機能であるため、安定した互換性の保証には含まれません。
UI、WebView2、Electron および各シグナルの設定については、デスクトップ UI フレームワーク、WebView2 モニタリング、Electron モニタリング、RUM 設定、Log 設定、Trace 設定を参照してください。
接続成功の確認¶
- アプリケーションを起動し、少なくとも 1 つの View を開きます。
- 1 回のクリック操作を行い、1 回の HTTP リクエストを送信します。
- 「RUM > エクスプローラー」で対象のアプリケーションを選択し、Session、View、Action、Resource のデータが表示されることを確認します。
- Log または Trace を有効にした後、ログデータと Trace Header/RUM Resource の関連付けが正常であることをそれぞれ確認します。
- Session Replay を有効にした後、Replay のアップロード診断ステータスが成功であることを確認し、セッション詳細でリプレイの入口を確認します。
コンソールにデータが表示されない場合は、トラブルシューティングを参照してください。
次のステップ¶
- 基本パラメーター、キャッシュ、診断、ライフサイクルの詳細設定:SDK 初期化
- RUM、Log、Trace の設定:RUM 設定、Log 設定、Trace 設定
- デスクトップ UI、WebView2、Electron:デスクトップ UI フレームワーク、WebView2 モニタリング、Electron モニタリング
- プライバシーとデータ保護:プライバシーと権限の説明
アップグレードと変更履歴¶
NuGet と vcpkg は独立したバージョンストリームを使用するため、バージョン番号が同じでも同一のリリースとして扱うことはできません:
| 配布方式 | バージョンタグ | 変更履歴 |
|---|---|---|
| NuGet / C# | nuget_<semver> |
C# 変更履歴 |
| vcpkg / Native C/C++ | vcpkg_<semver> |
Native C/C++ 変更履歴 |
安定版 1.2.3、および 1.2.3-alpha.1、1.2.3-beta.1 形式のプレリリース版をサポートします。アップグレード時は該当するパッケージの変更履歴をそれぞれ確認し、NuGet バージョンまたは vcpkg レジストリのベースラインを更新してください。2 つの配布ストリームは変更履歴でセクションを分けて掲載されています。
よくある質問¶
- Visual Studio の NuGet UI でパッケージが見つからない:「プレリリースを含む」を有効にするか、本記事に記載の
dotnet add packageコマンドを使用してください。 vcpkg installでポートが見つからない:vcpkg-configuration.jsonのレジストリ URL、packagesリスト、固定ベースラインが正しいことを確認し、プロジェクトのルートディレクトリでマニフェストモードによりインストールを実行してください。- .NET アプリケーションが Native DLL を読み込まない:プロジェクトのターゲットフレームワークが本ページに記載のサポート対象フレームワークであり、発行時の RID がデプロイ環境のアーキテクチャと一致していることを確認してください。