Electron 모니터링¶

Windows SDK는 Native Bridge를 통해 Electron에 연결합니다. Renderer의 Browser RUM 및 Browser Logs가 페이지 데이터를 수집하고, Electron Main Process가 데이터를 Windows Native Core에 전달합니다. Native Core는 애플리케이션 ID, Session, 샘플링, 글로벌 컨텍스트, 지속성 큐 및 업로드를 통합 관리합니다.

Native SDK의 초기화 소유자에 따라 다음 모드 중 하나를 선택합니다.

모드	사용 사례	vcpkg Feature	SDK 소유자
하이브리드 모드	C++ 데스크톱 애플리케이션에 Electron 페이지를 포함하는 경우	`electron-adapter`	C++ 호스트
전체 모드	애플리케이션 자체가 Electron인 경우	`electron-bridge`	`guance_windows_electron_bridge.exe`

두 모드를 동시에 사용할 수 없습니다. 페이지 측에서는 동일한 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 통합¶

의존성 설치¶

수집이 필요한 Renderer 프로젝트에 Browser SDK를 설치합니다.

npm install @cloudcare/browser-rum @cloudcare/browser-logs@^3.3.6

Browser Log를 수집하지 않는 경우 @cloudcare/browser-logs를 설치하지 않아도 됩니다.

빠른 시작에 따라 GuanceCloud vcpkg 레지스트리를 구성합니다. 현재 Electron Adapter는 동적 x64-windows만 지원합니다.

전체 모드는 electron-bridge를 사용합니다.

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "default-features": false,
      "features": ["electron-bridge"]
    }
  ]
}

하이브리드 모드는 electron-adapter를 사용합니다.

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "default-features": false,
      "features": ["electron-adapter"]
    }
  ]
}

vcpkg.json이 있는 디렉터리에서 다음을 실행합니다.

vcpkg install --triplet x64-windows

통합 시 다음 공개 진입점만 사용합니다.

electron/main/index.cjs: Main Process의 전체 모드 및 하이브리드 모드 진입점
electron/preload/standalone.cjs: 애플리케이션에 기존 Preload가 없는 경우 직접 사용
electron/preload/install.cjs: 애플리케이션에 기존 Preload가 있는 경우 bundler가 비즈니스 Preload에 병합

electron/internal/ 디렉터리의 파일을 복사, 수정 또는 직접 참조하지 마십시오.

개발 런타임에서는 프로젝트의 vcpkg_installed 디렉터리에서 Adapter를 로드하고, 패키징 후에는 process.resourcesPath에서 로드합니다.

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",
    );

const mainAdapterPath = path.join(
  sdkDirectory,
  "electron",
  "main",
  "index.cjs",
);

개발 디렉터리의 상대적 계층은 애플리케이션 구조에 따라 조정해야 하며, 현재 작업 디렉터리에 의존하거나 개발 머신의 절대 경로를 하드코딩하지 마십시오.

Native Bridge 초기화¶

하이브리드 모드¶

C++ 호스트가 먼저 Windows SDK를 초기화한 다음 Bridge Server를 기존 guance_sdk_handle에 바인딩합니다.

guance_sdk_handle sdk = guance_sdk_init(&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 { ipcMain } = require("electron");
const { connectMixedMode } = require(mainAdapterPath);

const rumBridge = await connectMixedMode({
  ipcMain,
  pipeName: "my-app-rum",
  enableAppLaunch: true,
});

하이브리드 모드에서는 다음을 준수합니다.

guance_windows_electron_bridge.exe를 시작하지 마십시오. 그렇지 않으면 두 번째 SDK Handle이 생성됩니다.
Electron은 더 이상 애플리케이션 ID, DataKit/Dataway, 캐시 또는 업로드 구성을 전달하지 않습니다.
C++ 호스트는 SDK Handle의 수명이 Bridge Server보다 길어야 함을 보장해야 합니다.
Browser Log를 수집하는 경우 Native 사용자 정의 로그를 동시에 활성화하고 logging_enabled를 1로 설정해야 합니다.

전체 모드¶

애플리케이션 자체가 Electron인 경우 Main Process가 Bridge EXE를 시작하고 관리합니다.

const { app, ipcMain } = require("electron");
const { startFullMode } = require(mainAdapterPath);

const rumBridge = await startFullMode({
  ipcMain,
  nativeDirectory: sdkDirectory,
  enableAppLaunch: true,
  nativeSettings: {
    applicationId: "<rum-application-id>",
    datakitUrl: "http://127.0.0.1:9529",
    service: "electron-desktop-client",
    environment: "prod",
    version: app.getVersion(),
    cachePath: path.join(app.getPath("userData"), "native-rum-cache"),
    sampleRate: 1,
    loggingEnabled: true,
    loggingSampleRate: 1,
    replayEnabled: false,
    replaySampleRate: 1,
    replayPrivacy: "mask",
    debug: false,
  },
});

Native RUM, Log 및 Replay의 샘플링 비율은 모두 0에서 1 사이의 값을 사용합니다. 애플리케이션 종료 전에 rumBridge.stop()이 완료될 때까지 기다려야 합니다.

connectMixedMode()와 startFullMode()는 기본적으로 enableAppLaunch를 활성화합니다. Adapter는 Electron 애플리케이션 수명 주기, 신뢰할 수 있는 창의 첫 번째 프레임 및 Browser View 컨텍스트를 결합하여 launch_cold, launch_hot Action을 자동으로 생성합니다. 자동 시작 Action이 필요하지 않은 경우 false로 설정합니다. 콜드 스타트가 첫 번째 Browser View와 연결되도록 하려면 가능한 한 빨리 Bridge를 시작하거나 연결하고, 창을 만든 후 즉시 attachWindow()를 호출해야 합니다.

Preload 및 창 연결¶

수집이 필요한 모든 창은 Guance Preload를 로드하고 attachWindow()를 통해 신뢰할 수 있는 창으로 등록해야 합니다. 다음 Electron 보안 구성을 유지합니다.

contextIsolation: true
nodeIntegration: false
sandbox: true

애플리케이션에 기존 Preload가 없는 경우 standalone.cjs를 직접 사용합니다.

const standalonePreloadPath = path.join(
  sdkDirectory,
  "electron",
  "preload",
  "standalone.cjs",
);

const window = new BrowserWindow({
  webPreferences: {
    preload: standalonePreloadPath,
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
});

const detachWindow = rumBridge.attachWindow(window);
window.webContents.once("destroyed", detachWindow);

애플리케이션에 기존 Preload가 있는 경우 electron/preload/install.cjs를 webpack, esbuild 등 bundler의 빌드 의존성으로 구성하고, 비즈니스 Preload에서 한 번 호출합니다.

const { installElectronRumPreload } = require("guance-electron-preload");

installElectronRumPreload();

여기서 guance-electron-preload는 install.cjs를 가리키는 빌드 별칭이며 npm 패키지가 아닙니다. sandbox: true를 활성화한 경우 최종 Preload 산출물은 webPreferences.preload로 직접 로드할 수 있는 번들이어야 합니다.

수집이 필요하지 않은 페이지는 Guance Preload를 로드하지 말고 attachWindow()를 호출하지 마십시오. 다중 창 애플리케이션의 경우 각 창을 독립적으로 등록하고, 창이 소멸될 때 attachWindow()가 반환한 제거 함수를 호출해야 합니다.

Renderer 초기화¶

모니터링이 필요한 각 Renderer는 Browser SDK를 초기화해야 합니다. Bridge 모드에서는 applicationId가 필요하지 않습니다. datakitOrigin은 Browser SDK의 초기화 유효성 검사를 통과하는 데만 사용되며, 데이터는 해당 주소로 업로드되지 않습니다.

import { datafluxRum } from "@cloudcare/browser-rum";
import { datafluxLogs } from "@cloudcare/browser-logs";

datafluxLogs.init({
  datakitOrigin: "http://127.0.0.1",
  forwardErrorsToLogs: true,
  forwardConsoleLogs: ["error", "warn"],
});

datafluxRum.init({
  datakitOrigin: "http://127.0.0.1",
});

const capabilities = JSON.parse(
  window.FTWebViewJavascriptBridge.getCapabilities(),
);
if (capabilities.includes("records")) {
  datafluxRum.startSessionReplayRecording();
}

Browser SDK는 FTWebViewJavascriptBridge를 감지하면 Bridge 전송으로 전환하고 Browser HTTP Batch를 시작하지 않습니다. 로그 샘플링은 Native loggingSampleRate로 통일하여 제어하는 것이 좋으며, 더 낮은 Browser sessionSampleRate를 설정하여 이중 샘플링이 발생하지 않도록 해야 합니다.

Session Replay는 실험적 기능이며 기본적으로 비활성화되어 있습니다

Native SDK와 Bridge 구성 모두 Replay가 활성화된 경우에만 getCapabilities()가 records를 반환합니다. Renderer는 이 기능에 따라 녹화를 시작할지 결정해야 하며, 단독으로 강제로 활성화할 수 없습니다. 하이브리드 모드에서는 Native Replay 구성, Bridge Server 구성 및 녹화 수명 주기가 일관되게 유지되어야 합니다.

리소스 패키징¶

electron-builder를 사용하는 경우 전체 모드는 전체 SDK 도구 디렉터리를 애플리케이션 리소스에 추가해야 합니다.

{
  "build": {
    "extraResources": [
      {
        "from": "vcpkg_installed/x64-windows/tools/guance-windows-native",
        "to": "guance-windows-native"
      }
    ]
  }
}

전체 모드는 동일한 SDK 버전의 Bridge EXE, Native DLL 및 electron/ 디렉터리를 제공해야 합니다. 하이브리드 모드는 tools/guance-windows-native/electron/만 복사하면 됩니다. Native DLL은 C++ 호스트의 기존 배포 프로세스에서 제공됩니다. 현재 작업 디렉터리나 개발 머신의 절대 경로에 의존하여 리소스를 찾지 마십시오.

통합 경계¶

Main Process는 electron/main/index.cjs의 공개 인터페이스만 사용하며, SDK 내부 IPC Channel을 자체적으로 등록하지 않습니다.
애플리케이션 ID, Client Token, DataKit/Dataway 주소, Native Session 또는 전체 Native 구성을 Renderer에 노출하지 마십시오.
Main Process는 신뢰할 수 있는 webContents만 등록합니다. 원격 페이지는 네비게이션, 팝업, 권한 및 허용된 도메인을 추가로 제한해야 합니다.
Trace는 Windows SDK Trace API를 통해 독립적으로 구성되며, Electron Adapter는 Trace 구성을 Renderer에 주입하지 않습니다.
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 및 Browser Log를 트리거하여 데이터가 Guance에 도달하는지 확인합니다.
데이터가 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 vcpkg Consumer Acceptance 및 Electron Sample을 참조하여 검증을 완료할 수 있습니다.