Canvas 기록 사용 설명서¶

개요¶

Guance Browser RUM은 Session Replay에서 Canvas 2D 화면을 기록할 수 있습니다. SDK 3.3.7부터 WebGL/WebGL2를 기록해야 하는 경우 WebGL Replay 플러그인을 추가로 설치할 수 있습니다.

Canvas 2D 기록 설정은 SDK 3.3.0부터 사용할 수 있습니다. WebGL Replay는 SDK 3.3.7부터 제공되며, RUM 메인 패키지 버전이 >= 3.3.7이어야 합니다. WebGL 플러그인은 RUM 메인 패키지와 동일한 SDK 릴리스 버전을 사용하는 것이 좋습니다. Canvas 2D의 >= 3.3.0 또는 일반 plugins 설정의 버전 요구사항만으로 WebGL이 사용 가능한지 판단할 수 없습니다.

먼저 가장 중요한 점을 설명합니다.

replayCanvasEnabled만 설정하는 것으로는 충분하지 않습니다.

Canvas 기록이 실제로生效하려면 적어도 다음 전제 조건을 동시에 충족해야 합니다.

• Session Replay 샘플링이 활성화되어 있어야 함
• 즉, sessionReplaySampleRate > 0이거나 sessionReplayOnErrorSampleRate가 적용됨
• Session Replay 기록이 시작되어 있어야 함
• 즉, startSessionReplayRecording()을 호출해야 함
• Canvas 기록이 활성화되어 있어야 함
• 즉, replayCanvasEnabled: true
• 페이지의 대상 요소가 Canvas 2D여야 함. WebGL/WebGL2의 경우 WebGL Replay 플러그인을 추가로 등록해야 함
• manual 모드인 경우 비즈니스 코드에서 snapshotCanvas(canvas)를 명시적으로 호출해야 함

현재 버전의 기능 범위는 다음과 같습니다.

• 수동 트리거 기록 지원
• 자동 기록 지원
• 자동 기록은 두 가지 공식 경로를 지원합니다.
• snapshot sampling
• higher-fidelity auto recording
• RUM 메인 패키지는 Canvas 2D를 직접 지원
• 선택적 WebGL Replay 플러그인은 WebGL/WebGL2의 예산 기반 픽셀 스냅샷 지원
• 기록 결과는 Session Replay 이벤트 스트림에 포함됨

현재 버전에서暂不覆盖하는 범위:

• WebGL 명령 수준 재생, 프레임별 비디오 기록
• OffscreenCanvas
• 모든 복잡한 2D 장면에 대해 완전히 동일한 복원

빠른 선택¶

최소 사용 가능 구성¶

다음은 현재 최소 사용 가능한 세 가지 구성입니다. 실제로 적용할 때는 여기서 직접 복사한 후 시나리오에 따라 추가하는 것이 좋습니다.

1. 수동 기록: 가장 안정적이고 권장¶

이 설정은 다음에 적합합니다.

• 화면이 언제 안정화되었는지 알고 있는 경우
• 주요 시점에 한 프레임만 추가로 캡처하면 되는 경우
• 비용을 최대한 제어하려는 경우

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,

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

datafluxRum.startSessionReplayRecording()

그런 다음 비즈니스 코드에서 명시적으로 프레임을 캡처합니다.

await datafluxRum.snapshotCanvas(canvasElement)

이 설정에서 반드시 명시적으로 설정해야 하는 것은 다음과 같습니다.

• sessionReplaySampleRate
• replayCanvasEnabled

함께 명시적으로 설정하는 것이 좋은 것은 다음과 같습니다.

• replayCanvasMode: 'manual'
• replayCanvasQuality: 'medium'

2. 자동 snapshot: 보다保守적인 자동 기록¶

이 설정은 다음에 적합합니다.

• 비즈니스에서 수동으로 프레임 캡처 시점을 조정하기 어려운 경우
• 안정성과 비용을 더 중요시하는 경우
• 자동 프레임 캡처가 프레임별 기록이 아니어도 괜찮은 경우

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,

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

datafluxRum.startSessionReplayRecording()

이 설정에서 명시적으로 설정하는 것이 좋은 것은 다음과 같습니다.

• replayCanvasEnabled: true
• replayCanvasMode: 'auto'
• replayCanvasSampling: 2
• replayCanvasQuality: 'medium'

replayCanvasSampling을 명시적으로 전달하지 않으면 SDK도 숫자 모드를 사용하지만, 기본값에 의존하여 접속 설명을 하는 것은 권장하지 않습니다. 명확하게 작성하는 것이 좋습니다.

3. 자동 고복원도 기록¶

이 설정은 다음에 적합합니다.

• 자동 모드가 실제 그리기 과정에 더 가깝기를 원하는 경우
• 페이지가 주로 2D canvas로 구성된 경우
• 복잡한 장면에서 자동으로 snapshot으로 폴백해도 괜찮은 경우

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,

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

datafluxRum.startSessionReplayRecording()

이 설정에서 반드시 명시적으로 설정해야 하는 것은 다음과 같습니다.

• replayCanvasEnabled: true
• replayCanvasMode: 'auto'
• replayCanvasSampling: 'all'

WebGL/WebGL2 플러그인 설정¶

WebGL 구현은 RUM 메인 패키지에 포함되어 있지 않습니다. 일반 DOM 및 Canvas 2D Replay는 플러그인을 설치할 필요가 없습니다. WebGL/WebGL2 Replay가 필요한 애플리케이션만 추가로 도입하면 됩니다. RUM 메인 패키지 버전은 >= 3.3.7이어야 하며, 플러그인은 메인 패키지와 동일한 SDK 릴리스 버전을 사용하는 것이 좋습니다.

WebGL 플러그인은 replayCanvasEnabled: true이고 replayCanvasMode: 'auto'인 경우에만 수집합니다. 이 플러그인은 그리기 경계의 예산 기반 픽셀 스냅샷을 기록하며, WebGL 명령 재생이나 프레임별 비디오가 아닙니다.

NPM¶

npm install @cloudcare/browser-rum @cloudcare/browser-rum-webgl

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

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 1000,
  replayCanvasQuality: 'medium',
  plugins: [webglReplayPlugin()]
})

datafluxRum.startSessionReplayRecording()
startWebGLEngine()

CDN¶

두 스크립트 모두 DATAFLUX_RUM.init() 이전에 로드되어야 합니다.

<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"></script>
<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum-webgl.js"></script>
<script>
  DATAFLUX_RUM.init({
    applicationId: '<YOUR_APPLICATION_ID>',
    datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
    sessionReplaySampleRate: 100,
    replayCanvasEnabled: true,
    replayCanvasMode: 'auto',
    replayCanvasSampling: 2,
    replayCanvasAutoInterval: 1000,
    replayCanvasQuality: 'medium',
    plugins: [DATAFLUX_RUM_WEBGL.webglReplayPlugin()]
  })

  DATAFLUX_RUM.startSessionReplayRecording()
  startWebGLEngine()
</script>

플러그인 초기화에 실패하거나 브라우저가 필요한 기능을 지원하지 않는 경우 WebGL 수집만 중단됩니다. 일반 DOM, Canvas 2D 및 기타 RUM 데이터는 계속 수집됩니다.

반드시 설정해야 할 사항¶

목표가 "canvas 기록을 일단 실행하는 것"이라면 최소한 다음 매개변수에 주의해야 합니다.

반드시 충족해야 하는 전제 조건¶

• sessionReplaySampleRate
• replay가 샘플링되도록 보장해야 합니다. 그렇지 않으면 canvas 기록이生效하지 않습니다.
• startSessionReplayRecording()
• init()만으로는 충분하지 않으며, 반드시 replay 기록을 실제로 시작해야 합니다.
• replayCanvasEnabled: true
• 이 설정을 켜지 않으면 canvas 기록이 완전히 비활성화됩니다.

수동 모드에서 반드시 설정해야 할 사항¶

• replayCanvasEnabled: true
• replayCanvasMode: 'manual'을 명시적으로 작성하는 것이 좋습니다.
• 비즈니스 코드에서 snapshotCanvas(canvas)를 호출해야 합니다.

자동 모드에서 반드시 설정해야 할 사항¶

• replayCanvasEnabled: true
• replayCanvasMode: 'auto'
• replayCanvasSampling을 명시적으로 작성하는 것이 좋습니다.
• 숫자: 자동 snapshot
• 'all': 더 높은 복원도의 자동 기록

replayCanvasWorkerUrl을 설정해야 하는 경우¶

이 매개변수는 "기능 스위치"가 아니라 배포 매개변수입니다.

다음 시나리오에서만 설정해야 합니다.

• 사이트 CSP가 worker-src blob:을 허용하지 않는 경우
• canvas snapshot 인코딩 worker를 별도로 호스팅하려는 경우
• canvas 인코딩이 inline blob worker를 사용하지 않도록 명시적으로 지정하려는 경우

일반적인 작성 방법:

datafluxRum.init({
  // ...
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

참고:

• replayCanvasWorkerUrl은 canvas snapshot 인코딩에만 영향을 줍니다.
• 원래 workerUrl을 대체하지 않습니다.
• 현재 프레임이 snapshot 인코딩을 거치지 않은 경우 canvas worker가 사용되지 않습니다.

모드 차이¶

manual¶

특징:

• 비즈니스에서 능동적으로 프레임 캡처 시점을 결정합니다.
• 중복 프레임을 제거하지 않습니다.
• "주요 시점에 한 프레임 캡처"에 가장 적합합니다.

적합한 경우:

• 차트 렌더링 완료
• 게임 결제 화면
• 화이트보드 저장
• 애니메이션 종료 후 최종 화면 캡처

auto¶

특징:

• SDK가 자동으로 프레임을 캡처합니다.
• 구체적인 프레임 캡처 방식은 replayCanvasSampling에 의해 결정됩니다.
• 페이지가 백그라운드로 전환되면 기록이 일시 중지되고, 포그라운드로 돌아오면 재개됩니다.
• shouldRecordCanvas()가 숫자 우선순위를 반환하도록 하여 중요한 canvas가 먼저 기록되도록 할 수 있습니다.

replayCanvasSampling의 공식적인 의미:

• 양수(2부터 시작 권장): 자동 snapshot 경로를 선택합니다. Canvas 2D의 경우 숫자 자체는 수집 빈도를 제어하지 않습니다.
• 'all': 더 높은 복원도의 자동 기록으로, 그리기 과정을 최대한 보존합니다. 복잡한 장면에서는 여전히 자동으로 snapshot으로 폴백될 수 있습니다.

자동 snapshot의 수집 템포는 replayCanvasAutoInterval, cooldown 및 backoff 설정에 의해 제어됩니다. WebGL 플러그인도 이러한 예산 제한의 영향을 받습니다. 'all'을 입력해도 WebGL은 여전히 픽셀 스냅샷을 사용하며, 'all'은 Canvas 2D만 command capture를 시도하게 합니다.

간단한 선택 제안:

• 설정 방법을 모르겠다면: 먼저 replayCanvasSampling: 2 사용
• 비용을 더 중요시하는 경우: replayCanvasAutoInterval 증가
• snapshot 연속성을 더 중요시하는 경우: replayCanvasAutoInterval을 점진적으로 감소
• Canvas 2D 그리기 복원도를 더 중요시하는 경우: 'all' 필요 여부 평가
• 더 높은 복잡성과 더 높은 데이터 비용을 명시적으로 수용할 수 있는 경우에만 'all' 사용

적합한 경우:

• 비즈니스에서 수동으로 프레임 캡처 시점을 조정하기 어려운 경우
• 페이지에 소량에서 중간 규모의 2D canvas가 있는 경우
• 비용과 복원도 사이의 균형을 원하는 경우
• 여러 차트가 있는 페이지에서 주요 차트만 우선 기록하면 되는 경우

사용 사례¶

적합한 사용 사례:

• 비즈니스에서 화면이 언제 안정화되는지 알고 있는 경우
• 주요 작업 후 수동으로 canvas 화면을 한 번 캡처해야 하는 경우
• Session Replay가 일부 2D canvas 시각적 결과를 복원할 수 있도록 해야 하는 경우

부적합한 사용 사례:

• 고주파 애니메이션의 프레임별 기록
• 모든 프레임에 대해 엄격한 복원이 필요한 비디오 방식 재생
• OffscreenCanvas 또는 WebGL 명령 수준 복원에 의존하는 장면

활성화 방법¶

NPM¶

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

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 100,
  trackUserInteractions: true,

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

datafluxRum.startSessionReplayRecording()

CDN¶

<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: '<YOUR_APPLICATION_ID>',
      datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
      service: 'browser',
      env: 'production',
      version: '1.0.0',
      sessionSampleRate: 100,
      sessionReplaySampleRate: 100,
      trackUserInteractions: true,

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

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

설정 항목 설명¶

일상적인 접속 시 우선 다음 6가지 설정에만 주의하면 됩니다.

• replayCanvasEnabled
• replayCanvasMode
• replayCanvasSampling
• replayCanvasQuality
• replayCanvasAutoInterval
• shouldRecordCanvas

나머지 매개변수는 고급 재정의 항목에 속합니다. 기본 정책이 현재 페이지에 적합하지 않다고 확인된 경우에만 계속 조정하십시오.

replayCanvasEnabled¶

• 유형: boolean
• 기본값: false

Canvas 기록 기능을 활성화할지 여부입니다.

항상 명시적으로 설정하는 것이 좋습니다. 기본적으로 비활성화되어 있을 때는 기존 일반 Session Replay 로직에 영향을 주지 않습니다.

replayCanvasMode¶

• 유형: string
• 현재 지원: 'manual' | 'auto'
• 기본값: 'auto'

Canvas 기록 모드를 지정합니다.

• manual: 비즈니스 코드에서 적절한 시점에 snapshotCanvas()를 명시적으로 호출
• auto: SDK가 자동으로 프레임을 캡처하며, 구체적인 전략은 replayCanvasSampling에 의해 결정됨

replayCanvasSampling¶

• 유형: number | 'all'
• 기본값: 숫자 모드

auto 모드에서의 canvas 기록 전략을 지정합니다.

• 숫자: snapshot sampling 사용
• 'all': 더 높은 복원도의 자동 기록 사용

권장 사항:

• 목표가 더 안정적이고保守적인 경우: 우선 숫자 모드 사용
• 목표가 실제 그리기 과정에 더 가까운 경우: 'all' 사용

참고:

• 'all'이 모든 장면에서 완전히 높은 복원도 경로로 기록된다는 의미는 아닙니다.
• 일부 복잡한 장면에서는 SDK가 자동으로 snapshot으로 폴백됩니다.
• 숫자 자체는 Canvas 2D의 수집 빈도를 제어하지 않습니다. 템포 조정이 필요할 때는 replayCanvasAutoInterval 및 cooldown/backoff 설정을 사용하십시오.
• WebGL은 항상 플러그인의 픽셀 스냅샷 경로를 사용하며, 2D command capture로 진입하지 않습니다.

replayCanvasQuality¶

• 유형: 'low' | 'medium' | 'high' | number
• 기본값: 0.4

Canvas 스냅샷 인코딩 품질입니다.

문자열 프리셋은 인코딩 품질과 자동 수집 예산을 동시에 조정하며, 이미지 품질만 조정하는 것이 아닙니다.

low, medium, high를 사용하지 않을 때 표의 "문자열 프리셋 미사용" 열이 런타임 기준 기본값입니다. 특정 설정을 명시적으로 전달하면 해당 설정이 프리셋의 해당 값을 재정의합니다. 예를 들어 replayCanvasQuality: 'medium'과 함께 replayCanvasAutoCooldown: 800을 사용하면 cooldown만 800 ms를 사용하고, 다른 항목은 medium의 값을 사용합니다.

Canvas 2D의 경우 replayCanvasAutoUnchangedBackoff는 시그니처가 계속 변경되지 않을 때 두 번의 전체 인코딩 검증 사이의 간격을 나타냅니다. 이 간격 내에서도 제한된 24x24 경량 시그니처 탐지가 실행되며, 약 1000 ms까지 점진적으로 백오프됩니다. 변경이 감지되면 전체 검증 간격이 끝날 때까지 기다리지 않고 즉시 대상 cadence를 복원합니다. WebGL은 계속해서 독립적이고 더保守적인 GPU 읽기 템포를 사용합니다.

replayCanvasAutoInterval은 각 Canvas의 대상 수집 간격을 나타내며, 전체 페이지의 고정 스캔 주기가 아닙니다. 여러 Canvas는 공정하게 라운드로빈되며, 라운드당 수, 동시성 및 전역 수집 예산의 제한을 계속 받습니다. 따라서 복잡한 대시보드의 단일 Canvas 실제 빈도는 목표 값보다 낮을 수 있습니다. 기본 전역 상한은 초당 약 16.7회의 snapshot attempt로, 메인 스레드와 업로드 부하가 Canvas 수에 따라 선형적으로 증가하는 것을 방지합니다.

위 표의 interval/cooldown은 Canvas 2D의 자동 snapshot 기준선입니다. WebGL 플러그인은 GPU 픽셀을 동기적으로 읽어야 합니다. 명시적으로 설정하지 않은 경우 더保守적인 템포를 계속 사용합니다. 기본값은 1000/1000 ms, low는 1500/3000 ms, medium은 1000/2000 ms, high는 700/1400 ms입니다. 명시적인 interval/cooldown만 WebGL 전략을 각각 재정의하여 2D 연속성을 높일 때 readPixels 비용이 자동으로 증가하는 것을 방지합니다.

이미지 인코딩 품질만 변경하고 샘플링 및 스케줄링 예산은 변경하지 않으려면 0에서 1 사이의 숫자를 전달하십시오(예: replayCanvasQuality: 0.4). replayCanvasSampling: 'all'에서 command 프레임 자체는 이미지 인코딩을 거치지 않지만, fallback snapshot은 여전히 여기의 품질 설정을 사용합니다.

숫자나 프리셋이 높을수록:

• 이미지 품질이 높아집니다.
• 볼륨이 일반적으로 커집니다.
• replay segment에 대한 부하도 커집니다.

먼저 medium부터 시작하는 것이 좋습니다.

기록 방법¶

API¶

현재 외부 API:

DATAFLUX_RUM.snapshotCanvas(canvasElement)

또는 NPM:

datafluxRum.snapshotCanvas(canvasElement)

반환값은 Promise이며, resolve되면 다음을 얻습니다.

{ ok: true }

또는:

{ ok: false, reason: '...' }

현재 발생할 수 있는 reason은 다음과 같습니다.

• not_recording
• replay_disabled
• invalid_mode
• not_canvas
• not_serialized
• detached
• rejected_by_should_record_canvas
• encode_too_large
• unchanged
• encode_failed
• observer_stopped

최소 예제¶

const canvas = document.getElementById('my-canvas')
const ctx = canvas.getContext('2d')

ctx.fillStyle = '#2563eb'
ctx.fillRect(20, 20, 160, 80)
ctx.fillStyle = '#0f172a'
ctx.font = '20px sans-serif'
ctx.fillText('Canvas Replay', 210, 70)

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.snapshotCanvas(canvas).then((result) => {
    if (!result.ok) {
      console.warn('snapshotCanvas failed:', result.reason)
    }
  })

권장 호출 시점¶

다음 시점에 호출하는 것이 좋습니다.

• 한 번의 그리기 완료 후
• 애니메이션 세트 종료 후
• 사용자가 주요 상호작용을 완료한 후

권장하지 않음:

• 모든 프레임에서 호출
• 고주파 타이머에서 호출
• 페이지 유휴 시간 외의 대량 배치 호출

기록生效 조건¶

Canvas snapshot이 실제로 replay에 포함되려면 다음 조건이 모두 충족되어야 합니다.

• init()이 호출되었음
• startSessionReplayRecording()이 호출되었음
• replayCanvasEnabled = true
• replayCanvasMode = 'manual' 또는 'auto'
• 전달된 요소가 HTMLCanvasElement임
• 노드가 현재 DOM snapshot에 이미 포함되어 있음
• 노드가 여전히 문서에 있음
• 인코딩 결과가 크기 제한을 초과하지 않음

이 중 하나라도 충족되지 않으면 이번 snapshot은 실패하거나 건너뜁니다.

shouldRecordCanvas 사용법¶

shouldRecordCanvas(canvas)는 이제 "기록 여부"를 제어할 수 있을 뿐만 아니라 auto 모드에서의 우선순위도 제어할 수 있습니다.

반환값 규칙:

• false 반환: 이 canvas를 기록하지 않음
• 숫자 반환: auto 모드 우선순위로, 숫자가 클수록 우선순위가 높음
• true, undefined 또는 기타 숫자가 아닌 truthy 값 반환: 기본 우선순위 0 사용

예제:

datafluxRum.init({
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasQuality: 'medium',
  shouldRecordCanvas(canvas) {
    if (canvas.dataset.replay === 'off') {
      return false
    }

    if (canvas.dataset.chartRole === 'primary') {
      return 10
    }

    if (canvas.dataset.chartRole === 'secondary') {
      return 5
    }

    return 0
  }
})

이는 대시보드에 매우 유용합니다.

• 주요 차트가 먼저 기록됨
• 보조 차트는 예산이 있을 때 계속 기록됨
• 관련 없는 작은 차트나 썸네일은 직접 제외 가능

고급 재정의 항목¶

기본 전략으로 충분하지 않은 경우에만 다음 하위 수준 매개변수를 고려하십시오.

• replayCanvasMimeType 인코딩 형식, 기본값 image/webp
• replayCanvasMaxCanvasSize 인코딩 전 허용되는 최대 변 길이, 기본값 1280
• replayCanvasMaxEncodedBytes 단일 프레임이 replay에 포함될 수 있는 최대 바이트 수, 기본값 40000
• replayCanvasMaxConcurrentEncodes 동시 인코딩 상한, 기본값 1
• replayCanvasFlushImmediately replay에 성공적으로 포함된 후 우선 flush할지 여부. manual 기본값 true, auto 기본값 false

다음 시나리오에서만 이러한 항목을 계속 조정하는 것이 좋습니다.

• 페이지의 canvas 수가 기본 예산보다 현저히 많은 경우
• 단일 프레임 크기가 너무 커서 크기나 바이트 수를 압축해야 하는 경우
• 디버그 결과를 통해 현재 템포가 너무 느리거나 빠르다고 확인한 경우

Demo 디버그 패널¶

이 저장소의 로컬 데모에는 현재 기록 링크를 관찰할 수 있는 canvas 디버그 패널이 포함되어 있습니다.

• mode: 현재 데모에서 사용하는 canvas 기록 모드
• auto policy: 현재 데모 초기화 시 전달된 interval / cooldown / unchanged backoff / failure backoff / max per run
• auto draw: 데모 자체의 지속적 다시 그리기 스위치, 화면 변경을 만들기 위해서만 사용됨
• last trigger: 가장 최근 수동 snapshotCanvas()의 트리거 소스
• last snapshot: 가장 최근 수동 snapshotCanvas()의 결과
• last reason: 가장 최근 실패 이유
• auto result: 현재 설정에 따라 도출된 전략 결과 표시
• last event: 데모 측에서 기록한 가장 최근 이벤트 상태

현재 데모는 두 가지 보조 기능도 제공합니다.

• toggle auto draw: 주기적으로 canvas를 다시 그려 auto 모드에서 지속적으로 변경이 발생하는지 관찰
• export last canvas event: 가장 최근에 성공한 수동 snapshot에 해당하는 디버그 이벤트 내보내기

참고:

• auto draw는 데모 동작이며, SDK 내부의 자동 샘플러가 아닙니다.
• auto result는 현재 수동 snapshotCanvas() 결과를 기반으로 한 전략 매핑이며, 주로 디버그 설명에 사용됩니다.
• 아직 SDK 내부 auto 정기 샘플링 결과에 직접 연결되지 않았습니다.
• 내보낸 이벤트도 데모 측에서 현재 canvas 내용에 따라 재구성한 디버그 샘플이며, 수집 페이로드에서 직접 읽어온 것이 아닙니다.

성능 권장 사항¶

Canvas 기록은 고비용 기능이므로保守적으로 사용하는 것이 좋습니다.

권장 방법:

• 주요 시점에만 snapshotCanvas() 호출
• canvas 크기 제어
• replayCanvasQuality: 'low' | 'medium' | 'high' 우선 사용
• replayCanvasMaxConcurrentEncodes = 1 유지
• auto 모드에서는 quality 프리셋이 기본 예산을 결정하도록 우선 설정
• 대시보드 페이지에서는 shouldRecordCanvas()를 우선 사용하여 주요 차트 필터링 및 우선순위 정렬

권장하지 않음:

• 고주파 애니메이션을 프레임별로 캡처. WebGL은 더 큰 replayCanvasAutoInterval에서 시작한 후 재생 연속성과 페이지 성능에 따라 점진적으로 조정
• 대형 캔버스에 빈번하게 호출
• canvas 기록을 기본 경로로 사용

개인정보 보호 설명¶

다음 사항에 주의해야 합니다.

• canvas 픽셀 내용은 일반 DOM masking에 의해 자동으로 보호되지 않습니다.

즉:

• 텍스트 노드, 폼 노드, 속성 마스킹 규칙이 canvas 픽셀에 자동으로 적용되지 않습니다.
• canvas에 민감한 정보가 그려진 경우, 기록 후 replay에서 복원될 수 있습니다.

따라서 권장 사항:

• 공개적으로 재생 가능한 canvas에 대해서만 기록 활성화
• 계정, 휴대폰 번호, 결제 정보 등 민감한 내용이 포함된 canvas에 대해 snapshotCanvas()를 호출하지 마십시오.

자주 묻는 질문¶

1. snapshotCanvas()를 호출했지만 replay에 화면이 표시되지 않는 이유는 무엇입니까?¶

우선 확인할 사항:

• replayCanvasEnabled가 활성화되었는지
• session replay recording이 시작되었는지
• 전달된 요소가 canvas인지
• canvas 그리기가 완료된 후에 호출되었는지
• 크기가 너무 커서 폐기되었는지

2. 자동 모드가 프레임별로 기록되지 않는 이유는 무엇입니까?¶

현재 버전은 이미 자동 기록을 지원하지만, "프레임별 비디오"가 아닙니다.

이유는 다음과 같습니다.

• snapshot sampling은 본질적으로 여전히 샘플링입니다.
• 더 높은 복원도의 자동 기록은 실제 그리기에 더 가깝지만, 여전히 복잡한 장면 경계와 자동 폴백 제약의 영향을 받습니다.
• canvas 인코딩 및 업로드 비용은 여전히 일반 DOM replay보다 현저히 높습니다.
• WebGL은 선택적 플러그인의 예산 기반 픽셀 스냅샷을 사용하며, 마찬가지로 프레임별로 기록하지 않습니다.

따라서 현재 자동 모드의 설계 목표는 다음과 같습니다.

• 낮은 비용으로 주요 시각적 상태를 캡처
• 복원도와 비용 사이의 균형 유지
• Session Replay를 비디오 기록으로 만들지 않음

3. WebGL에 화면이 표시되지 않는 이유는 무엇입니까?¶

우선 확인할 사항:

• RUM 메인 패키지가 3.3.7 이상 버전이고, 호환되는 WebGL Replay 플러그인이 추가로 설치 또는 로드되었는지. 플러그인은 메인 패키지와 동일한 SDK 릴리스 버전을 사용하는 것이 좋습니다.
• webglReplayPlugin()이 plugins에 포함되었는지
• replayCanvasEnabled: true와 replayCanvasMode: 'auto'가 동시에 활성화되었는지
• 플러그인/RUM init()이 WebGL 엔진 로드 및 context 생성보다 먼저 실행되었는지
• observer 시작 후에도 실제 draw가 계속 발생하는지

WebGL의 첫 번째 안전 화면은 observer 시작 후 다음 실제 그리기에서 비롯됩니다. 플러그인은 이미 그리기가 완료된 기본 framebuffer를 비동기적으로 읽지 않으며, WebGL을 일반 Canvas 2D snapshot 경로로 폴백하지 않습니다.

4. Canvas 기록은 별도로 업로드됩니까?¶

아닙니다.

현재 버전에서 canvas 스냅샷은 replay 이벤트의 일부로 인코딩되며, 일반 replay와 동일한 업로드 링크를 공유합니다.

5. 대시보드 페이지에서 일부 차트는 기록되었지만 일부는 기록되지 않은 이유는 무엇입니까?¶

이런 유형의 페이지는 일반적으로 많은 수의 canvas 차트가 동시에 존재합니다. "일부 차트가 기록되지 않음" 현상이 발생할 때 가장 일반적인 이유는 단일 차트 오류가 아니라 다음과 같습니다.

• 자동 모드의 각 라운드가 모든 차트를 기록하지는 않을 수 있습니다.
• 동일 화면에 차트가 너무 많아 자동 기록 예산이 부족합니다.
• 일부 차트의 초기 그리기가 너무 빨라서 이후에 다시 그려지지 않습니다.
• 일부 복잡한 차트는 자동 고복원도 모드에서 snapshot으로 폴백되어 비용이 더 높아집니다.

우선 다음과 같이 처리하는 것이 좋습니다.

1. 페이지의 핵심 요구사항이 "차트를 최대한 놓치지 않는 것"이라면 우선 다음을 사용하십시오.

replayCanvasEnabled: true,
replayCanvasMode: 'auto',
replayCanvasSampling: 'all'

1. 최초 화면의 중요 차트에 대해 차트 렌더링이 완료된 후 수동으로 한 프레임을 캡처합니다.

await datafluxRum.snapshotCanvas(canvas)

1. 중요하지 않은 차트는 계속 자동 모드에 맡깁니다.

2. shouldRecordCanvas()를 사용하여 중요 차트의 우선순위를 높이거나 중요하지 않은 작은 차트를 건너뜁니다.

shouldRecordCanvas(canvas) {
  if (canvas.dataset.miniChart === 'true') {
    return false
  }

  if (canvas.id === 'main-trend' || canvas.id === 'conversion-funnel') {
    return 10
  }

  return 1
}

모든 차트를 커버하는 것보다 안정성과 비용을 더 중요시한다면:

• replayCanvasSampling: 2 유지
• 중요 차트에 대해서만 수동으로 snapshotCanvas(canvas) 호출

커버리지를 더 중요시한다면:

• replayCanvasSampling: 'all' 시도
• 중요 차트에 대해 수동 프레임 캡처 추가

간단히 이해하면:

• 자동 모드는 "가능한 한 기록"을 담당
• 수동 snapshotCanvas(canvas)는 "중요 차트가 반드시 기록되도록" 보장

예제 시나리오¶

직접 도입하기에 적합한 비즈니스 시나리오:

• 차트 그리기 완료 후 한 번 기록
• 레벨 종료 시 한 번 기록
• 화이트보드 저장 전 한 번 기록
• 서명 확인 후 한 번 기록

더 완전한 예제:

function drawInvoicePreview(canvas, data) {
  const ctx = canvas.getContext('2d')
  ctx.clearRect(0, 0, canvas.width, canvas.height)
  ctx.fillStyle = '#fff'
  ctx.fillRect(0, 0, canvas.width, canvas.height)
  ctx.fillStyle = '#111827'
  ctx.font = '18px sans-serif'
  ctx.fillText('Invoice Preview', 24, 36)
  ctx.fillText('Order: ' + data.orderNo, 24, 72)
  ctx.fillText('Amount: ' + data.amount, 24, 108)
}

function refreshPreview(canvas, data) {
  drawInvoicePreview(canvas, data)
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.snapshotCanvas(canvas)
}

대시보드 시나리오 예제:

datafluxRum.init({
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasQuality: 'medium',
  shouldRecordCanvas(canvas) {
    if (canvas.dataset.miniChart === 'true') {
      return false
    }

    if (canvas.id === 'main-trend' || canvas.id === 'conversion-funnel') {
      return 10
    }

    return 1
  }
})

이 설정의 의미는 다음과 같습니다.

• 작은 보조 차트는 건너뜁니다.
• 주요 트렌드 차트와 핵심 퍼널 차트를 우선 기록합니다.
• 기타 일반 차트는 동일한 우선순위에서 라운드로빈 샘플링됩니다.

권장 사항¶

현재 버전에서 권장하는 사용 방식은 단 한 가지입니다.

• Canvas 기록을 "중요 시각적 상태 프레임 캡처"로 간주하고, "지속적인 비디오 기록"으로 간주하지 마십시오.

비즈니스 시점이 명확하다면 우선 manual을 사용하십시오. 대시보드와 같은 다중 차트 시나리오라면 auto를 신중하게 활성화하고, 숫자 sampling 또는 'all'을 명확히 선택하십시오.