クイックスタート¶

Windows SDK は、独立した 2 つのパッケージを提供しています。.NET/C# アプリケーションは NuGet から Guance.Windows を、Native C/C++ アプリケーションは GuanceCloud の 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 の使用¶

GuanceCloud レジストリの設定¶

プロジェクトのルートディレクトリに vcpkg-configuration.json を作成するか、更新します。デフォルトのレジストリベースラインは、プロジェクトで検証済みの Microsoft vcpkg のコミットに置き換えてください。<latest-guance-vcpkg-registry-commit> は、GuanceCloud レジストリの最新コミットを表します。導入時には、プレースホルダーを実際のコミットに置き換え、固定して、再現可能なビルドを確保してください。

{
  "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-guance-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);

初期化を 1 回実行した後、アプリケーション終了前にキューを明示的に処理し、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 設定の送信先アドレス許可リストを使用して、ヘッダーを注入できるリクエストを制限してください。
• 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 がデプロイ環境のアーキテクチャと一致していることを確認してください。