콘텐츠로 이동

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 런타임 소스 SDK 소유자
혼합 모드(external) C++ 데스크톱 애플리케이션에 Electron 페이지를 임베드 호스트가 제공, 예: vcpkg 기본 패키지 C++ 호스트
전체 모드(managed) 애플리케이션 자체가 Electron npm 설치 시 다운로드하며 디렉터리를 명시적으로 지정할 수도 있음 Adapter가 관리하는 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 연동

종속성 설치

Electron Native Adapter 버전

애플리케이션 본체가 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를 시작하지 마세요. 그렇지 않으면 두 번째 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을 다운로드하지 않습니다. 애플리케이션 루트 디렉터리에서 실행합니다:

npx guance-electron-native --sdk-version vcpkg_0.1.0-alpha.10 --target win32-x64 --with-replay

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

설치 프로그램은 두 매니페스트의 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를 활성화할 필요는 없습니다:

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

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

vcpkg install --triplet x64-windows

위 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를 사용했거나 다른 대상 아키텍처가 필요한 경우 애플리케이션 루트 디렉터리에서 실행합니다:

npx guance-electron-native --sdk-version <sdk-tag> --target <target>

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 HTTPS 미러 사용, 디렉터리 구조는 /<sdk-tag>/<filename>
GUANCE_NATIVE_SKIP_DOWNLOAD 1로 설정하면 런타임 설치를 건너뛰며 external 모드에 적합

압축 파일은 지정된 SDK 버전 및 아키텍처와 일치해야 합니다. 오프라인 Native Runtime만 제공한다고 해서 npm이 완전히 오프라인인 것은 아닙니다. npm 패키지 및 해당 종속성 캐시도 미리 준비해야 합니다. 프라이빗 소스 checkout은 자동 다운로드를 건너뛰므로, 로컬 file: 종속성으로 연동 테스트할 때는 런타임을 직접 준비해야 합니다.

연동 경계

  • Main Process는 @cloudcare/electron-native-adapter가 내보내는 공용 인터페이스만 사용하며 SDK 내부 IPC Channel을 직접 등록하지 않습니다.
  • Renderer에 애플리케이션 ID, Client Token, DataKit/Dataway 주소, 네이티브 Session 또는 전체 Native 구성을 노출하지 마세요.
  • Main Process는 신뢰할 수 있는 webContents만 등록합니다. 원격 페이지는 내비게이션, 팝업, 권한 및 허용 도메인도 제한해야 합니다.
  • 전체 모드에서는 native.settings로 Native Trace를 구성하고 혼합 모드에서는 호스트가 구성합니다. Adapter는 Renderer에 Trace 구성을 주입하지 않으며, 이로 인해 페이지 요청에 Trace Header가 자동으로 추가되지 않습니다.
  • Renderer JavaScript Error 및 Long Task는 Browser RUM이 수집합니다. unresponsive, render-process-gone 및 Main Process Crash는 Bridge가 자동으로 보고하지 않으므로 필요 시 Electron crashReporter 또는 다른 Crashpad 서비스를 별도로 연동해야 합니다.

연동 검증

  1. Renderer DevTools Network에 RUM 또는 Log 직접 전송 요청이 없는지 확인합니다.
  2. View, Action, Resource, Error, Long Task 및 Browser Log 하나를 트리거하여 콘솔에서 데이터를 확인합니다.
  3. 데이터가 Native 구성의 애플리케이션 ID, Session ID 및 sdk_name=df_windows_rum_sdk를 사용하는지 확인합니다.
  4. Browser Log의 warn 상태가 Native Log에서 warning으로 표시되고 사용자 정의 속성이 유지되는지 확인합니다.
  5. Replay가 꺼져 있거나 구성 요소가 없는 경우 getCapabilities()에 records가 포함되지 않는지 확인합니다. 구성 요소를 설치하고 활성화한 후 녹화 데이터가 정상적으로 보고되는지 확인합니다.
  6. 혼합 모드에서 Electron 페이지를 닫은 후 C++ SDK가 계속 실행되는지 확인합니다. 전체 모드에서 애플리케이션을 종료한 후 Bridge EXE가 정상적으로 종료되는지 확인합니다.

Windows SDK 저장소의 Electron Native Adapter Consumer Acceptance 및 Electron Sample을 참조하여 인수 테스트를 완료할 수 있습니다. 로컬 연동 테스트에는 npm file: 종속성을 사용할 수 있습니다. 정식 애플리케이션에서는 릴리스 패키지를 사용하고 애플리케이션의 lockfile로 실제 설치 버전을 관리합니다.

문서 평가

이 페이지가 도움이 되었나요?