세션 리플레이(Session Replay) 연동 방법¶

설정¶

표의 interval/cooldown 기본값은 Canvas 2D용입니다. WebGL 플러그인이 이 두 항목을 명시적으로 설정하지 않은 경우 더 보수적인 GPU 읽기 백(readback) 속도를 유지하여 기본적으로 readPixels 비용이 증가하는 것을 방지합니다.

표의 기본값은 low, medium, high 문자열 사전 설정을 사용하지 않은 경우에 적용됩니다. 문자열 사전 설정은 quality, sampling, interval, cooldown, unchanged/failure backoff 및 max-per-run을 동시에 대체합니다. 명시적인 개별 설정은 사전 설정의 해당 값을 덮어씁니다. 이미지 품질만 변경하려면 replayCanvasQuality에 0에서 1 사이의 숫자를 전달해야 합니다. 전체 매트릭스는 Canvas 녹화 사용 설명서를 참조하세요.

Canvas 2D 녹화 설정은 SDK 3.3.0부터 사용할 수 있습니다. WebGL Replay는 SDK 3.3.7부터 제공되며, RUM 메인 패키지 버전 >= 3.3.7이 필요하고, WebGL 플러그인을 메인 패키지와 동일한 SDK 릴리스 버전으로 사용할 것을 권장합니다.

Session Replay 활성화¶

기존 SDK 도입 방식을 통해 NPM 패키지를 > 3.0.0 버전으로 교체하거나, 기존 CDN 링크를 https://static.guance.com/browser-sdk/v3/dataflux-rum.js로 변경합니다. SDK 초기화 init() 이후 Session Replay Record 데이터가 자동으로 수집되지는 않으며, startSessionReplayRecording을 실행하여 데이터 수집을 시작해야 합니다. 이는 특정 상황에서만 Session Replay Record 데이터를 수집하는 경우에 유용합니다. 예를 들어:

// 로그인한 사용자의 작업 데이터만 수집
if (user.isLogin()) {
  DATAFLUX_RUM.startSessionReplayRecording()
}

Session Replay 데이터 수집을 중지해야 하는 경우 stopSessionReplayRecording()을 호출하여 종료할 수 있습니다.

NPM¶

@cloudcare/browser-rum 패키지를 가져오고, @cloudcare/browser-rum의 버전이 > 3.0.0인지 확인하세요. 녹화를 시작하려면 초기화 후 datafluxRum.startSessionReplayRecording()을 실행하세요.

import { datafluxRum } from '@cloudcare/browser-rum'

datafluxRum.init({
  applicationId: '<DATAFLUX_APPLICATION_ID>',
  datakitOrigin: '<DATAKIT ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  trackInteractions: true,
})

datafluxRum.startSessionReplayRecording()

CDN¶

기존 CDN 주소 https://static.guance.com/browser-sdk/v2/dataflux-rum.js를 https://static.guance.com/browser-sdk/v3/dataflux-rum.js로 변경하고, DATAFLUX_RUM.init() 실행 후 DATAFLUX_RUM.startSessionReplayRecording()을 실행하세요.

<script
src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
type="text/javascript"
></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
    applicationId: '<DATAFLUX_APPLICATION_ID>',
    datakitOrigin: '<DATAKIT ORIGIN>',
    service: 'browser',
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 100,
    trackInteractions: true,
})

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

오류 관련 Session Replay 데이터만 수집하는 방법 (SDK 버전 ≥3.2.19 필요)¶

기능 설명¶

페이지에서 오류가 발생하면 SDK는 자동으로 다음 작업을 수행합니다.

1. 소급 수집: 오류 발생 1분 전의 전체 페이지 스냅샷을 기록합니다.
2. 지속 녹화: 오류 발생 시점부터 세션이 종료될 때까지 계속 기록합니다.
3. 지능형 보상: 독립적인 샘플링 채널을 통해 오류 시나리오의 전체 커버리지를 보장합니다.

설정 예시¶

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// SDK 핵심 설정 초기화
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   // 필수 매개변수
   applicationId: '<DATAFLUX_APPLICATION_ID>',
   datakitOrigin: '<DATAKIT_ORIGIN>',

   // 환경 식별자
   service: 'browser',
   env: 'production',
   version: '1.0.0',

   // 샘플링 전략 설정
   sessionSampleRate: 100,          // 전체 기본 세션 수집 (100%)
   sessionReplaySampleRate: 0,       // 일반 화면 녹화 샘플링 비활성화
   sessionReplayOnErrorSampleRate: 100, // 오류 시나리오 100% 샘플링

   // 보조 기능
   trackInteractions: true          // 사용자 행동 추적 활성화
});

// 화면 녹화 엔진 강제 활성화 (반드시 호출)
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Canvas 녹화 설명¶

canvas 녹화는 기본적으로 자동으로 활성화되지 않습니다. 실제로 작동하려면 최소한 다음 조건을 모두 충족해야 합니다.

• Session Replay가 샘플링되었음
• 즉, sessionReplaySampleRate > 0이거나 sessionReplayOnErrorSampleRate에 적중했음
• startSessionReplayRecording() 호출됨
• replayCanvasEnabled: true 설정됨
• 대상 요소가 Canvas 2D임; WebGL/WebGL2는 추가로 WebGL Replay 플러그인을 등록해야 함

manual 모드를 사용하는 경우, 비즈니스 코드에서 직접 호출해야 합니다.

datafluxRum.snapshotCanvas(canvas)

Canvas 관련 매개변수 중 필수로 간주해야 하는 항목¶

실제 연동 시 다음 항목을 필수로 간주하는 것이 좋습니다.

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

replayCanvasMode === 'auto'인 경우 다음 항목을 명시적으로 설정하세요.

• replayCanvasSampling
• 양수: 자동 스냅샷 경로 선택, 2부터 시작 권장
• 'all': 더 높은 정확도의 자동 녹화, 그리기 과정 재현이 중요한 페이지에 적합
• replayCanvasAutoInterval
• 자동 스냅샷의 스케줄링 간격 제어; 숫자 sampling 자체는 Canvas 2D 빈도를 제어하지 않음

세 가지 권장 최소 설정¶

수동 녹화¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

자동 스냅샷¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 250,
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

자동 고정확도 녹화¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 'all',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

CSP 시나리오¶

사이트의 CSP가 worker-src blob:을 허용하지 않는 경우, 다음을 설정할 수 있습니다.

datafluxRum.init({
  // ...
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

주의 사항:

• replayCanvasWorkerUrl은 canvas 스냅샷 인코딩에만 영향을 미칩니다.
• workerUrl을 대체하지 않습니다.
• 모든 canvas 프레임이 canvas worker를 사용하는 것은 아닙니다.

자세한 내용은 CSP 보안 정책을 참조하세요.

Canvas 2D, WebGL/WebGL2의 전체 기능 경계, 선택적 플러그인 연동 및 성능 권장 사항은 Canvas 녹화 사용 설명서를 참조하세요. WebGL 플러그인은 RUM 메인 패키지와 동일한 SDK 버전을 사용해야 하며, WebGL 엔진이 context를 생성하거나 그리기 메서드를 캐시하기 전에 RUM init()을 완료해야 합니다.

Wujie 마이크로 프론트엔드와 open Shadow DOM¶

RUM SDK 3.3.11부터 Session Replay는 iframe JavaScript realm에서 생성된 후 현재 페이지의 open ShadowRoot에 마운트된 기본 폼 요소와 Canvas를 인식할 수 있습니다. 이러한 구조는 Wujie 마이크로 프론트엔드에서 흔히 볼 수 있습니다. 요소가 여전히 iframe realm의 프로토타입을 유지하지만, 현재 페이지가 접근할 수 있는 Shadow DOM 콘텐츠에 이미 속해 있습니다.

• input, textarea, select의 사용자 입력 및 변경 이벤트는 리플레이에 포함될 수 있습니다. 요소가 Replay DOM에 진입한 후, JavaScript를 통해 value, checked, selectedIndex 속성을 수정하는 것도 기록될 수 있습니다.
• open ShadowRoot 내의 DOM 구조 및 이후 DOM 변경 사항은 리플레이에 포함될 수 있습니다.
• Canvas는 여전히 replayCanvasEnabled: true를 설정해야 하며, 이 페이지에서 설명한 수집 모드와 예산을 따라야 합니다. replayCanvasSampling: 'all'이 Canvas 명령 수집을 활성화하면, 현재 페이지 realm의 Canvas는 계속 그리기 명령을 수집하고, iframe realm 간 Canvas는 자동으로 비트맵 스냅샷으로 대체됩니다.
• mode: 'closed'인 Shadow DOM과 iframe 내부 문서에 남아 있는 콘텐츠는 이 지원 범위에 포함되지 않습니다.

여기서 "iframe realm"은 요소가 iframe의 JavaScript 환경에 의해 생성되었음을 의미할 뿐, SDK가 iframe 내부 문서를 녹화한다는 의미는 아닙니다. 현재 페이지가 접근할 수 있는 open ShadowRoot에 마운트된 콘텐츠만 일반 페이지 DOM처럼 Session Replay에 포함됩니다.

주의 사항¶

일부 HTML 요소가 재생 시 보이지 않음¶

세션 리플레이는 iframe 내부 문서를 기록하지 않으며, 비디오, 오디오의 미디어 콘텐츠도 수집하지 않습니다. 관련 요소 자체와 오디오/비디오 재생 상태는 여전히 기록에 포함될 수 있습니다. 현재 구현은 접근 가능한 open Shadow DOM을 지원합니다. mode: 'closed'인 Shadow DOM은 수집을 보장할 수 없습니다. Web Components의 완전한 기록 가능 여부는 Shadow Root가 열려 있는지와 내부에서 사용하는 콘텐츠 유형에 따라 달라집니다.

FONT 또는 IMG가 올바르게 표시되지 않음¶

Session Replay는 비디오가 아니라 DOM 스냅샷 기반으로 재구성된 iframe입니다. 따라서 리플레이는 페이지의 다양한 정적 리소스(font, image)에 의존합니다.

다음과 같은 이유로 리플레이 시 정적 리소스를 사용할 수 없을 수 있습니다.

• 해당 정적 리소스가 더 이상 존재하지 않음. 예를 들어 이전 배포의 일부인 경우.
• 해당 정적 리소스에 접근할 수 없음. 예를 들어 인증이 필요하거나 내부 네트워크에서만 접근 가능한 경우.

• CORS(일반적으로 웹 폰트)로 인해 브라우저가 정적 리소스를 차단함.

• 리플레이 시 iframe에 해당하는 guance.com 샌드박스 환경을 기반으로 하므로, 특정 정적 리소스가 특정 도메인에 대한 권한을 부여받지 않은 경우 브라우저가 해당 요청을 차단합니다.

• Access-Control-Allow-Origin 헤더를 통해 guance.com이 웹사이트가 의존하는 모든 font 또는 image 정적 리소스에 접근할 수 있도록 허용하여 리플레이 시 해당 리소스에 접근할 수 있도록 보장하세요.

자세한 내용은 교차 출처 리소스 공유를 참조하세요.

CSS 스타일이 올바르게 적용되지 않거나 마우스 호버 이벤트가 리플레이되지 않음¶

font 및 image와 달리 Session Replay Record는 CSSStyleSheet 인터페이스를 활용하여 적용된 다양한 CSS 규칙을 기록 데이터의 일부로 묶으려고 시도합니다. 실행할 수 없는 경우 CSS 파일 링크를 기록하는 것으로 대체됩니다.

올바른 마우스 호버 지원을 받으려면 CSSStyleSheet 인터페이스를 통해 CSS 규칙에 접근할 수 있어야 합니다.

스타일 파일이 웹 페이지와 다른 도메인에서 호스팅되는 경우, CSS 규칙에 대한 접근은 브라우저의 교차 출처 보안 검사의 적용을 받으며, 브라우저가 crossorigin 속성을 사용하여 CORS를 활용하는 스타일 파일을 로드하도록 지정해야 합니다.

예를 들어, 애플리케이션이 example.com 도메인에 있고 link 요소를 통해 assets.example.com의 CSS 파일에 의존하는 경우 crossorigin 속성을 anonymous로 설정해야 합니다.

<link rel="stylesheet" crossorigin="anonymous"
      href="https://assets.example.com/style.css">

또한 assets.example.com에서 example.com 도메인을 승인해야 합니다. 이를 통해 리소스 파일이 Access-Control-Allow-Origin 헤더를 설정하여 리소스를 올바르게 로드할 수 있습니다.

더 읽어보기¶