クイックスタート¶

Windows SDK は、独立してリリースされる 2 つのパッケージを提供します。.NET/C# アプリケーションは NuGet から Guance.Windows を使用し、Native C/C++ アプリケーションは SDK の vcpkg レジストリから guance-windows-native を使用します。両者は同じ RUM アプリケーション ID とデータ送信方法を使用しますが、パッケージのバージョン、リリースサイクル、更新ログは互いに独立しています。

前提条件¶

1. RUM で「カスタム」アプリケーションを作成し、アプリケーション ID を取得します。
2. いずれかのデータ送信方法を準備します。
3. パブリック DataWay：送信 URL と Client Token
4. ローカル環境デプロイ（DataKit）：アプリケーションプロセスからアクセス可能な DataKit アドレス
5. アプリケーションが Windows 10 以降で動作していることを確認します。

導入手順¶

1. アプリケーションの技術スタックに応じて、NuGet または vcpkg パッケージを選択します。
2. 依存関係をインストールし、RUM アプリケーションと送信設定を設定します。
3. SDK を初期化し、必要に応じて自動収集、Log、Trace、Session Replay を有効にします。
4. アプリケーションを実行し、コンソールでデータが正常に送信されることを確認します。

パッケージの選択¶

.NET / C#：NuGet の使用¶

プロジェクトディレクトリでインストールします：

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

または、プロジェクトファイルに追加します：

<PackageReference Include="Guance.Windows" Version="[latest_version]" />

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 でポートを宣言します：

{
  "dependencies": [
    "guance-windows-native"
  ]
}

その後、マニフェストモードでインストールします：

vcpkg install

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 を参照してください。

最小限の初期化例¶

初期化時には、RUM アプリケーション ID、サービス名、環境、アプリケーションバージョンを必ず指定してください。パブリック DataWay モードでは、DatawayUrl と ClientToken を使用します。ローカル環境デプロイ（DataKit）を使用する場合は、DatakitUrl のみを設定し、パブリック Token は不要です。

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.<your-domain>",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});

GuanceSdk.EnableAutomaticInstrumentation();

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_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.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);
if (sdk == nullptr) {
    // 初期化失敗を処理します。
}

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_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.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);

初期化後、アプリケーションの終了前にキューを明示的に処理して SDK をシャットダウンします：

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(sdk);
guance_sdk_shutdown(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. アプリケーションを起動し、少なくとも 1 つの View を開きます。
2. クリック操作を 1 回実行し、HTTP リクエストを 1 回発行します。
3. RUM > エクスプローラー で該当するアプリケーションを選択し、Session、View、Action、Resource データが表示されることを確認します。
4. Log または Trace を有効にした後、ログデータと Trace Header / RUM Resource の関連付けがそれぞれ正常であることを確認します。
5. Session Replay を有効にした後、Replay アップロードの診断ステータスが成功であることを確認し、セッション詳細でリプレイエントリを確認します。

コンソールにデータがない場合は、トラブルシューティング を参照してください。

次のステップ¶

• 基本パラメータ、キャッシュ、診断、ライフサイクルの完全な設定：SDK 初期化
• RUM、Log、Trace の設定：RUM 設定、Log 設定、Trace 設定
• デスクトップ UI、WebView2、Electron：デスクトップ UI フレームワーク、WebView2 モニタリング、Electron モニタリング
• プライバシーとデータ保護：プライバシーと権限の説明

アップグレードと更新ログ¶

NuGet と vcpkg は独立したバージョンストリームを使用するため、バージョン番号が同じでも、同じリリースとは見なせません：

安定版 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 がデプロイ環境のアーキテクチャと一致していることを確認してください。