Electron モニタリング¶
このページでは、Windows ネイティブホスト、ランタイム、Replay、およびパッケージングの説明を扱います。初めて導入する場合は、Electron アプリケーションの統合 から方式を選択してください。アプリケーション本体が Electron の場合は、先に managed クイックスタート を完了してください。
Windows SDK は Native Bridge を介して Electron に統合します。Renderer 内の Browser RUM と Browser Logs がページデータの収集を担当し、Electron Main Process がデータを Windows Native Core に渡します。Native Core がアプリケーション ID、Session、サンプリング、グローバルコンテキスト、永続化キュー、アップロードを一元的に管理します。
Native SDK の初期化の所有者に応じて、いずれかのモードを選択します:
| モード | ユースケース | Native Runtime の提供元 | SDK 所有者 |
|---|---|---|---|
ハイブリッドモード(external) |
C++ デスクトップアプリケーションに Electron ページを埋め込む | ホストが提供(例:vcpkg 基本パッケージ) | C++ ホスト |
フルモード(managed) |
アプリケーション自体が Electron | npm インストール時にダウンロードされ、ディレクトリの明示指定にも対応 | Adapter が管理する Bridge EXE |
2 つのモードを同時に使用することはできません。ページ側は同じ Preload、attachWindow()、Renderer の初期化方法を共有します。
この方法は Web RUM の Electron 単独統合 とは異なります。Windows SDK 統合では、Renderer はデータを直接アップロードせず、実際のアプリケーション ID、送信先アドレス、Client Token も設定しません。
データフローは次のとおりです:
Electron Renderer
@cloudcare/browser-rum / @cloudcare/browser-logs コレクター
|
| FTWebViewJavascriptBridge.sendEvent(JSON)
v
安全な Preload -> ホワイトリスト IPC -> Electron Main Process
|
v
Windows Native Core(C++ ホストまたは Bridge EXE によって初期化)
ネイティブ RUM / Log / セッション / サンプリング / コンテキスト / 永続化 / アップロード
Electron への統合¶
依存関係のインストール¶
アプリケーション本体が Electron の場合は、共通クイックスタート に従って依存関係をインストールし、Main、Preload、Renderer を統合します。Electron のバージョン要件は サポート範囲 を参照してください。
npm のインストールとランタイムインストーラーには Node.js 18+ が必要です。パッケージ化されたアプリケーションのユーザーは、Node.js を別途インストールする必要はありません。Windows は x64、x86(Electron/Node.js では ia32)、arm64 をサポートしており、実行時アーキテクチャに一致する Microsoft Visual C++ v14 Redistributable と Windows Universal CRT のインストールが必要です。
公開されている npm パッケージ自体には Native バイナリは同梱されていませんが、postinstall がプラットフォームとアーキテクチャに応じて Native Runtime をダウンロードして検証するため、ローカルでのコンパイルは不要です。フルモードでは、このランタイムがデフォルトで自動的に特定されるため、vcpkg を事前にインストールする必要はありません。Adapter は macOS にも対応しています。このページでは Windows Native Bridge の統合について説明します。
重要なバージョン情報
Adapter 0.1.0-alpha.3 では、Windows x86/arm64 のランタイム選択、検証、およびパッケージングのサポートが追加され、デフォルトの Native Runtime が Windows SDK vcpkg_0.1.0-alpha.8、macOS SDK 1.6.8-alpha.6 に固定されました。これらはこのバージョンのデフォルトの依存関係であり、以降のバージョンが常に同じ Native SDK を使用することを保証するものではありません。
Adapter、Windows SDK、macOS SDK はそれぞれバージョンを管理します。実際のデフォルト値は、インストールされている npm パッケージの package.json.nativeRuntime に従います。
Windows Replay を別パッケージで導入する場合は、Adapter 0.1.0-alpha.5 と Windows SDK vcpkg_0.1.0-alpha.10 以降が必要です。alpha.5 はデフォルトでこの Windows SDK を使用します。基本ランタイムにはデフォルトで Replay が含まれないため、同じバージョン、同じアーキテクチャの補助コンポーネントを明示的にインストールする必要があります。
ハイブリッドモードのみを使用する場合は、インストール前に PowerShell 環境変数 $env:GUANCE_NATIVE_SKIP_DOWNLOAD = "1" を設定すると、使用しないランタイムのダウンロードをスキップできます。フルモードに切り替えてインストールする前に、この変数をクリアしてください。
Native Bridge の初期化¶
フルモード¶
Electron Main Process が Bridge EXE を起動および管理します。完全な初期化と終了の例は managed クイックスタート を参照してください。共通の native.settings フィールド、サンプリング単位、バージョン差異については Main 設定 を参照してください。
Windows でキャッシュディレクトリをカスタマイズする必要がある場合は、cachePath を path.join(app.getPath("userData"), "native-rum-cache") に設定できます。ここで path は node:path モジュール、app は Electron App です。
その他のオプション設定:
| 場所 | パラメーター | 説明 |
|---|---|---|
native.settings |
traceType |
デフォルトは w3c_traceparent |
native.settings |
traceAllowedUrls |
Native Trace URL ルールの文字列 |
native.settings |
httpTimeoutMs |
アップロードタイムアウト。デフォルトは 10000 ミリ秒、範囲は 1..300000 |
native(managed) |
readyTimeoutMs、stopTimeoutMs |
起動ハンドシェイクと終了待機時間。デフォルトは 10000、3000 ミリ秒 |
native(managed) |
onNativeOutput |
(stream, text) を受け取り、Bridge の標準出力とエラー出力の診断に使用 |
native(external) |
timeoutMs、retryDelayMs |
接続タイムアウトとリトライ間隔。デフォルトは 10000、100 ミリ秒 |
bootstrap() |
enableAppLaunch |
デフォルトは true。コールドスタートおよびホットスタートの Action を自動収集 |
native |
mode |
managed はフルモード、external はハイブリッドモード |
native(managed) |
directory |
Native Runtime ディレクトリをカスタマイズ。省略時は自動的に特定される |
bootstrap() |
onError |
非同期転送とウィンドウ処理のエラーを受け取る |
終了時のクリーンアップと共通 Client API については ライフサイクルと診断 を参照してください。startFullMode() と connectMixedMode() は旧バージョンとの互換性のためにのみ残されています。新規の統合では bootstrap() を統一して使用してください。
Adapter はデフォルトで enableAppLaunch を有効にしており、Electron アプリケーションのライフサイクル、信頼できるウィンドウの最初のフレーム、Browser View のコンテキストを組み合わせて、launch_cold、launch_hot Action を自動生成します。自動起動 Action が不要な場合は false に設定してください。コールドスタートを最初の Browser View に関連付けるため、できるだけ早く Bridge を起動または接続し、ウィンドウ作成後すぐに attachWindow() を呼び出してください。
ハイブリッドモード¶
C++ ホストは最初に Windows SDK を初期化し、その後 Bridge Server を既存の guance_sdk_handle にバインドします:
guance_sdk_config_v2 config{};
guance_sdk_config_v2_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-application-id>";
config.session_sampling_rate = 100.0f; // vcpkg 0.1.0-alpha.9 以降でサポート
guance_sdk_handle sdk = guance_sdk_init_v2(&config);
guance_electron_bridge_server_options options{};
guance_electron_bridge_server_options_init(&options);
options.pipe_name = "my-app-rum";
options.logging_enabled = 1;
options.session_replay_enabled = 0;
options.replay_privacy_level = "mask";
guance_electron_bridge_server_handle bridge =
guance_electron_bridge_server_start(sdk, &options);
// アプリケーション終了時は、最初に Bridge Server を停止してから SDK をシャットダウンします。
guance_electron_bridge_server_stop(bridge);
guance_sdk_shutdown(sdk);
Electron Main Process は同じ名前の named pipe に接続します:
const electron = require("electron");
const { bootstrap } = require("@cloudcare/electron-native-adapter");
const rumBridge = await bootstrap({
electron,
native: {
mode: "external",
pipeName: "my-app-rum",
},
enableAppLaunch: true,
});
ハイブリッドモードでは:
guance_windows_electron_bridge.exeを起動しないでください。起動すると 2 つ目の SDK Handle が作成されます。- Electron はアプリケーション ID、DataKit/Dataway、キャッシュ、アップロード設定を渡しません。
- C++ ホストは、SDK Handle のライフサイクルが Bridge Server より長くなることを保証する必要があります。
- Browser Log を収集する場合は、Native カスタムログも有効にし、
logging_enabledを1に設定する必要があります。
Preload とウィンドウの統合¶
共通 Preload 設定 に従ってブリッジをインストールし、ウィンドウ管理 に従ってページを読み込む前にウィンドウを登録します。managed と external はこのフローを共有します。
Renderer の初期化¶
共通 Renderer の統合 に従って、ページ RUM、オプションのログ、Replay を初期化します。実際のアプリケーション ID、アップロード先、認証情報は Native が管理します。
Session Replay は実験的な機能であり、デフォルトでは無効です
Native SDK と Bridge の両方の設定で Replay が有効になっており、対応する Replay コンポーネントが実際に利用可能な場合にのみ、getCapabilities() は records を返します。Renderer はこの機能に基づいて録画を開始するかどうかを決定する必要があり、単独で強制的に有効にすることはできません。フルモードでは native.settings で replayEnabled: true を設定します。ハイブリッドモードでは、ホストが Native SDK と Bridge Server を設定し、録画のライフサイクルを管理します。
オプションの Replay ランタイムのインストール¶
フルモードでは、開発またはビルド段階で Replay 補助パッケージをインストールします。アプリケーションの実行時に DLL をダウンロードすることはありません。アプリケーションのルートディレクトリで次を実行します:
CLI が出力するランタイムディレクトリは、開発時には native.directory に渡し、パッケージング時には stageWindowsRuntime() の nativeDirectory に渡します。パッケージ化後は、resources/native が自動的に使用されます。x86、arm64 の場合は、それぞれ win32-x86、win32-arm64 を選択してください。また、npm インストール前に $env:GUANCE_NATIVE_INSTALL_REPLAY = "1" を設定すると、postinstall が補助コンポーネントを npm パッケージのランタイムディレクトリにインストールし、その後デフォルトの方法で特定およびパッケージ化されます。
オフラインインストールでは、基本アーカイブと Replay アーカイブ、およびそれぞれの .sha256 ファイルを準備する必要があります:
npx guance-electron-native --sdk-version vcpkg_0.1.0-alpha.10 --target win32-x64 --runtime-archive C:/sdk/runtime.tar.gz --replay-archive C:/sdk/replay.tar.gz
インストーラーは、2 つのマニフェストの SDK バージョン、アーキテクチャ、ファイルハッシュを検証し、guance_windows_replay.dll を基本 DLL と同じディレクトリに配置します。インストール後も replayEnabled: true を設定する必要があります。Replay がない場合、または読み込めない場合でも、通常の RUM は動作し続け、Renderer は records 機能を取得しません。
ハイブリッドモードのコンポーネントは、C++ ホストが vcpkg の replay Feature を通じて提供し、DLL はホストの基本 SDK と同じディレクトリに配置されます。Electron Adapter は、Bridge Server のハンドシェイクで得られた実際の機能に基づいて、Replay を転送するかどうかを決定します。詳細は オプションコンポーネントのインストール を参照してください。
リソースのパッケージング¶
フルモードでは、アプリケーションの署名前に、公開されているパッケージング用ヘルパー関数を呼び出して、完全なランタイムを ASAR の外にコピーする必要があります:
const { stageWindowsRuntime } = require(
"@cloudcare/electron-native-adapter/packaging/windows",
);
stageWindowsRuntime({
resourcesDirectory: "release/MyApp-win32-x64/resources",
arch: "x64",
});
ヘルパー関数は、デフォルトで npm パッケージ内にインストールされているランタイムを特定し、resources/native にコピーします。コピー先のディレクトリは空である必要があります。パッケージ化後の managed モードはこのディレクトリを自動的に特定するため、native.directory を設定する必要はありません。Native EXE、DLL、manifest などのリソースは完全な状態で保持し、app.asar には入れないでください。
Replay がインストールされている場合、stageWindowsRuntime() は補助 DLL と replay-manifest.json も検証してコピーします。基本ランタイムと Replay 補助コンポーネントは、同じバージョンおよびアーキテクチャである必要があります。
クロスアーキテクチャのパッケージングを行う場合は、先に対象のランタイムをインストールし、その後に対象の arch を明示的に渡します。Windows は x64、x86 / ia32、arm64 をサポートしています。CLI でインストールしたランタイムは、ヘルパー関数の nativeDirectory で指定する必要があります。
vcpkg のツールディレクトリを手動で使用する場合は、electron-builder の extraResources を使ってコピーし、後述の vcpkg セクションの sdkDirectory でリソースの場所を指定することもできます:
{
"build": {
"extraResources": [
{
"from": "vcpkg_installed/x64-windows/tools/guance-windows-native",
"to": "guance-windows-native"
}
]
}
}
フルモードでは、同じ SDK バージョンの guance_windows_electron_bridge.exe と隣接する guance_windows_native.dll を提供する必要があります。同時に、アプリケーションのパッケージングツールが @cloudcare/electron-native-adapter を含める必要があります。ハイブリッドモードでは vcpkg ツールディレクトリをコピーする必要はありません。Native DLL は引き続き C++ ホストの既存のデプロイフローで提供され、JavaScript Adapter は npm 依存関係として提供されます。リソースの特定を現在の作業ディレクトリや開発マシンの絶対パスに依存させないでください。
オプション:vcpkg による Native Runtime の提供¶
ホストが Native SDK を保有している場合、またはランタイムを自分でビルドする必要がある場合は、クイックスタート に従って SDK の vcpkg レジストリを設定します。JavaScript Adapter は引き続き npm で個別にインストールします。フルモードのランタイムを手動で提供する場合は、electron-bridge を有効にします:
{
"dependencies": [
{
"name": "guance-windows-native",
"default-features": false,
"features": ["electron-bridge"]
}
]
}
ハイブリッドモードでは、基本の Native パッケージをインストールします。Replay を使用する場合は、その依存関係に "features": ["replay"] を追加します。古い electron-bridge Feature を有効にする必要はありません:
vcpkg.json があるディレクトリで次を実行します:
上記の vcpkg コマンドは x64 を例としています。vcpkg のツールディレクトリを手動で使用する場合は、以下の sdkDirectory を native.directory に渡します。デフォルトの npm ダウンロードフローでは、この項目を設定する必要はありません:
const path = require("node:path");
const { app } = require("electron");
const sdkDirectory = app.isPackaged
? path.join(process.resourcesPath, "guance-windows-native")
: path.resolve(
__dirname,
"../../../vcpkg_installed/x64-windows/tools/guance-windows-native",
);
開発ディレクトリの相対階層はアプリケーションの構成に合わせて調整してください。現在の作業ディレクトリに依存したり、開発マシンの絶対パスをハードコードしたりしないでください。
カスタムおよびオフラインのランタイムインストール¶
npm インストール時に --ignore-scripts を使用した場合、または別のターゲットアーキテクチャが必要な場合は、アプリケーションのルートディレクトリで次を実行できます:
Windows のターゲットは win32-x64、win32-x86、win32-arm64 で、macOS は darwin-universal です。<sdk-tag> には Native SDK Release の完全なタグを使用し、vcpkg_、nuget_、v などの既存のプレフィックスを保持します。タグに対応するランタイムアセットが存在している必要があります。
オフラインインストールには、SDK の .tar.gz と隣接する .tar.gz.sha256 検証ファイルが必要です:
npx guance-electron-native --sdk-version <sdk-tag> --target <target> --runtime-archive C:/sdk/runtime.tar.gz
CLI はランタイムをアプリケーションのルートディレクトリにインストールします。開発時は出力ディレクトリを native.directory に渡し、パッケージング時は stageWindowsRuntime() の nativeDirectory に渡します。パッケージ化後は、開発用ディレクトリの設定を削除し、自動的に特定される resources/native を使用します。
npm の postinstall では、以下の環境変数を使用できます(PowerShell では $env:変数名 = "値" で設定します):
| 環境変数 | 用途 |
|---|---|
GUANCE_NATIVE_RUNTIME_ARCHIVE |
ローカル SDK アーカイブと隣接する検証ファイルを使用し、ダウンロードを置き換える |
GUANCE_NATIVE_INSTALL_REPLAY |
1 に設定すると、Windows の postinstall で Replay 補助コンポーネントを明示的にインストールする |
GUANCE_NATIVE_REPLAY_ARCHIVE |
ローカルの Replay アーカイブと隣接する検証ファイルを使用する。CLI で使用する場合は Replay インストールも暗黙的に有効になる |
GUANCE_NATIVE_REPLAY_ASSET_NAME |
Replay 補助アーカイブのダウンロードファイル名を上書きする |
GUANCE_NATIVE_RUNTIME_TARGET |
ターゲットのプラットフォームとアーキテクチャを指定する |
GUANCE_NATIVE_SDK_VERSION |
パッケージ内で固定されている Native SDK タグを上書きする |
GUANCE_NATIVE_RUNTIME_ASSET_NAME |
ダウンロードするアセットのファイル名を上書きする |
GUANCE_NATIVE_RUNTIME_DOWNLOAD_BASE_URL |
ディレクトリ構造が /<sdk-tag>/<filename> の HTTPS ミラーを使用する |
GUANCE_NATIVE_SKIP_DOWNLOAD |
1 に設定するとランタイムのインストールをスキップする。external モード向け |
アーカイブは、指定された SDK バージョンおよびアーキテクチャと一致している必要があります。オフラインの Native Runtime を提供するだけでは、npm が完全にオフラインになるわけではありません。npm パッケージとその依存関係のキャッシュも事前に準備する必要があります。非公開ソースの checkout では自動ダウンロードがスキップされるため、ローカルで file: 依存関係を使用して結合テストを行う場合は、ランタイムを自分で準備する必要があります。
統合の境界¶
- Main Process は、
@cloudcare/electron-native-adapterがエクスポートする公開インターフェースのみを使用し、SDK 内部の IPC Channel を独自に登録しないでください。 - アプリケーション ID、Client Token、DataKit/Dataway アドレス、ネイティブ Session、完全な Native 設定を Renderer に公開しないでください。
- Main Process は信頼できる
webContentsのみを登録します。リモートページでは、ナビゲーション、ポップアップ、権限、許可するドメインも制限する必要があります。 - フルモードでは
native.settingsを使用して Native Trace を設定し、ハイブリッドモードではホストが設定します。Adapter は Trace 設定を Renderer に注入せず、その結果としてページリクエストに Trace Header を自動的に追加することもありません。 - Renderer の JavaScript Error と Long Task は Browser RUM が収集します。
unresponsive、render-process-gone、Main Process Crash は Bridge が自動的に報告しないため、必要に応じて Electron のcrashReporterや他の Crashpad サービスを別途導入してください。
統合の検証¶
- Renderer の DevTools Network で、RUM または Log の直接アップロードリクエストがないことを確認します。
- View、Action、Resource、Error、Long Task、および 1 件の Browser Log をトリガーし、コンソールでデータを確認します。
- データが Native 設定のアプリケーション ID、Session ID、
sdk_name=df_windows_rum_sdkを使用していることを確認します。 - Browser Log の
warnステータスが Native Log ではwarningとして表示され、カスタム属性が保持されていることを確認します。 - Replay が無効、またはコンポーネントがない場合は、
getCapabilities()にrecordsが含まれないことを確認します。コンポーネントをインストールして有効にした後、録画データが正常に送信されることを確認します。 - ハイブリッドモードでは Electron ページを閉じた後も C++ SDK が動作し続けることを確認します。フルモードではアプリケーションを終了した後、Bridge EXE が正常に終了することを確認します。
Windows SDK リポジトリの Electron Native Adapter Consumer Acceptance と Electron Sample を参考に、受け入れテストを完了できます。ローカルでの結合テストには npm の file: 依存関係を使用できます。正式なアプリケーションではリリースパッケージを使用し、アプリケーションの lockfile で実際にインストールされるバージョンを管理してください。