Web 애플리케이션 연동¶

이 페이지 구성을 완료하면 Browser RUM SDK가 페이지 View, 리소스 요청, 프런트엔드 오류, 사용자 작업을 자동으로 수집하여 Guance로 데이터를 전송합니다.

연동 경로 선택¶

먼저 애플리케이션 형태에 따라 진입 방식을 선택하여 View가 중복 구성되거나 서버 렌더링 단계에서 브라우저 API에 접근하는 것을 방지합니다.

연동 정보 준비¶

1. 「실제 사용자 모니터링(RUM) > 애플리케이션 목록 > 애플리케이션 생성 > Web」으로 이동합니다.
2. 애플리케이션을 생성하고 콘솔에서 생성된 applicationId, env, version 등 구성을 확인합니다.

3. 데이터 전송 방식을 선택합니다:

4. 공용 OpenWay: site와 clientToken을 획득하며 DataKit 배포가 필요 없습니다.

5. DataKit 직접 연결: datakitOrigin을 준비합니다. DataKit에서 RUM 수집기를 활성화하고 공용망에서 접근 가능하며 IP 지리 정보 라이브러리가 설치된 상태로 구성합니다.

데이터 전송 방식¶

{
  applicationId: "<APPLICATION_ID>",
  datakitOrigin: "<DATAKIT_ORIGIN>"
}

{
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>"
}

SDK 통합¶

NPM 연동¶

프런트엔드 프로젝트에서 SDK를 설치하고 불러옵니다:

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

프로젝트에서 SDK를 초기화합니다:

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

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN 동기 로드¶

HTML 파일에 스크립트를 추가합니다:

<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: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

CDN 비동기 로드¶

HTML 파일에 스크립트를 추가합니다:

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.guance.com/browser-sdk/v3/dataflux-rum.js",
    "DATAFLUX_RUM"
  )
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
  })
</script>

위 예시는 공용 OpenWay를 사용합니다. DataKit 직접 연결을 사용할 때는 site와 clientToken을 제거하고 datakitOrigin을 구성하세요.

슬림 RUM SDK¶

RUM SDK 3.3.3부터 슬림 버전을 제공합니다. 슬림 버전은 전체 버전과 동일한 초기화 방식을 사용하며 View, Resource, Long Task, Error, Action, 사용자 및 글로벌 Context, 사용자 정의 이벤트, 분산 추적 등 일반적인 RUM 기능을 지원합니다. 페이지 녹화가 필요 없고 프런트엔드 번들 크기를 줄이려는 애플리케이션에 적합합니다.

NPM 연동¶

일반 RUM 패키지를 동일 버전의 슬림 패키지로 교체합니다:

npm install @cloudcare/browser-rum-slim @cloudcare/browser-core

import { datafluxRum } from "@cloudcare/browser-rum-slim"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN 연동¶

동기 또는 비동기 로드 방식은 전체 버전과 동일하며, 스크립트 파일 이름만 슬림 버전에 해당하는 파일로 교체하면 됩니다. 다음은 동기 로드 예시입니다:

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum-slim.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

전체 버전과의 기능 차이¶

슬림 버전에는 다음 기능이 포함되지 않습니다:

• Session Replay 및 startSessionReplayRecording(), stopSessionReplayRecording(), isRecording() 등 녹화 API.
• Canvas 2D, WebGL/WebGL2 녹화 및 snapshotCanvas() 등 Canvas API.
• compressIntakeRequests 전송 압축 및 해당 Worker.

슬림 버전은 sessionReplaySampleRate, sessionReplayOnErrorSampleRate, replayCanvasEnabled를 강제로 비활성화하고 compressIntakeRequests를 강제로 false로 설정합니다. 연동 시 이러한 구성을 전달하지 말고 workerUrl이나 replayCanvasWorkerUrl도 설정할 필요가 없습니다. 이후에 세션 리플레이, Canvas 녹화 또는 압축 전송이 필요하면 NPM 패키지 또는 CDN 파일을 전체 버전으로 다시 전환하면 되며, 다른 기본 초기화 파라미터는 계속 사용할 수 있습니다.

연동 확인¶

1. SDK가 연동된 페이지를 열고 페이지 이동, 버튼 클릭, API 요청을 한 번씩 수행합니다.
2. 브라우저 개발자 도구의 Network에서 /v1/write/rum을 필터링하여 성공한 전송 요청이 있는지 확인합니다.
3. Console에서 Application ID is not configured, datakitOrigin or site is not configured 등 초기화 오류가 없는지 확인합니다.
4. 「RUM > 애플리케이션 목록」으로 이동하여 해당 Web 애플리케이션을 열고 탐색기에서 service, env, version으로 필터링하여 View, Resource 또는 Action 데이터가 있는지 확인합니다.

자주 사용하는 선택 구성¶

기본 데이터 확인이 끝나면 필요에 따라 다른 기능을 활성화합니다:

분산 추적 구성(선택)¶

NPM + TypeScript 연동 시 traceType는 해당 브랜드의 browser-core 패키지에서 가져온 TraceType 열거형을 사용해야 합니다:

import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  allowedTracingUrls: ["https://api.example.com"],
  traceType: TraceType.DDTRACE
})

TraceType.DDTRACE의 런타임 값은 여전히 "ddtrace"입니다. CDN 연동에는 모듈 임포트가 없으므로 명시적으로 구성할 때 해당 런타임 문자열을 사용합니다. 분산 추적을 활성화한 후에는 API 서버에서 해당 Trace Header도 허용해야 합니다. 자세한 내용은 APM과 RUM 연동을 참조하세요.

일반 Session이 샘플링에 포함되지 않았지만 Trace Header를 백엔드에 전달해야 하는 경우 allowTraceHeaderWithoutSession을 명시적으로 활성화할 수 있습니다:

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 0,
  sessionOnErrorSampleRate: 0,
  allowedTracingUrls: ["https://api.example.com"],
  allowTraceHeaderWithoutSession: true
})

활성화하면 SDK는 여전히 allowedTracingUrls에 해당하는 XHR 및 Fetch 요청에만 Trace Header를 주입합니다. 이 구성은 RUM Session을 생성하거나 강제로 활성화하지 않으며, 샘플링에 포함되지 않은 Session의 View, Error, Resource, Action 데이터도 전송하지 않습니다. API 서비스에서도 선택한 traceType에 해당하는 요청 헤더를 허용해야 하며, 크로스 오리진 요청에는 CORS도 올바르게 구성해야 합니다.

파라미터 구성¶

초기화 파라미터¶

low, medium, high 문자열 프리셋을 사용하지 않는 경우 Canvas 자동 스케줄링 기준은 sampling 2, Canvas별 목표 interval 250 ms, cooldown 250 ms, unchanged backoff 3000 ms, failure backoff 5000 ms, 라운드당 최대 2개 Canvas입니다. 문자열 프리셋은 이러한 예산과 인코딩 품질을 동시에 대체하며, 여러 Canvas는 공정한 순환과 글로벌 수집 예산에 의해 제한됩니다. 명시적인 개별 구성은 프리셋의 해당 값을 덮어씁니다. 전체 프리셋 매트릭스는 Canvas 녹화 사용 설명서에서 확인할 수 있습니다.

위의 고빈도 스케줄링 기준은 Canvas 2D에 적용됩니다. WebGL 플러그인은 interval/cooldown을 명시적으로 구성하지 않으면 더 보수적인 GPU readback 속도를 유지하며, 명시적인 개별 구성이 있을 때만 각각 덮어씁니다.

site 파라미터 처리¶

런타임 Session 제어¶

RUM SDK 3.3.6에 startSession()이 추가되었습니다. 호출하면 현재 Session이 즉시 종료되고 현재 샘플링 구성에 따라 Session이 다시 시작되며, 다음 사용자 상호작용을 기다릴 필요가 없습니다:

datafluxRum.startSession()

런타임 sessionSampleRate도 함께 재정의할 수 있습니다:

datafluxRum.startSession({
  sessionSampleRate: 100,
})

샘플링 비율은 0에서 100 사이여야 합니다. 이 재정의 값은 현재 및 이후 자동으로 이어지는 Session에 적용됩니다. 전체 RUM 패키지와 슬림 RUM 패키지 모두 이 API를 지원합니다. 자세한 의미와 사용 사례는 런타임에서 Session 다시 시작을 참조하세요.

필요에 따라 고급 기능 활성화¶

오류 세션 이벤트만 수집¶

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

• 지속 기록: 오류 발생 시점부터 세션 전체 수명 주기 데이터를 완전하게 기록합니다.
• 정밀 보상: 독립적인 샘플링 채널을 통해 오류 시나리오가 누락되지 않도록 보장합니다.

구성 방식¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 0,
    sessionOnErrorSampleRate: 100
  })

위 예시는 공용 OpenWay를 사용합니다. DataKit 직접 연결 시 기본 연동 예시에 따라 전송 주소 필드를 교체하세요.

데이터 압축¶

JS, CSS, 이미지 등 많은 정적 리소스를 수집하면서 전체 수집을 활성화하면 SDK 초기화 후 데이터가 많아져 요청이 쌓이고 애플리케이션 스레드 상태에 영향을 줄 수 있습니다.

compressIntakeRequests: true로 설정하면 SDK는 Web Worker에서 deflate로 전송 데이터를 압축하여 요청 크기와 요청 수를 줄입니다.

구성 예시¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    compressIntakeRequests: true
  })

주의 사항¶

1. 데이터 압축 로직은 Web Worker에서 실행됩니다. CSP 보안 정책이 활성화된 경우 worker-src에서 blob:을 허용해야 합니다. 자세한 내용은 CSP 보안 정책 설명을 참조하세요.
2. SDK는 workerUrl 구성 항목을 통해 자체 호스팅 Worker 주소를 지정할 수 있습니다.
3. 이 기능을 사용하려면 SDK 버전이 >= 3.2 이상이어야 합니다.

사용자 정의 데이터 및 이벤트¶

기본 연동 페이지에서는 모든 공용 API를 다시 다루지 않습니다. 비즈니스 목표에 따라 해당 페이지로 이동하면 CDN, NPM 및 전체 파라미터 예시를 확인할 수 있습니다:

• 사용자 작업 추적: 클릭 자동 수집, Action 이름 정의, 사용자 정의 Action 추가.
• 사용자 지정 식별자: 로그인 후 사용자를 설정하고, 로그아웃하거나 계정을 전환할 때 사용자 정보를 제거합니다.
• 글로벌 컨텍스트: 이후 모든 RUM 이벤트에 안정적인 비즈니스 차원을 추가합니다.
• 사용자 정의 Action 추가: 페이지 클릭으로 표현할 수 없는 비즈니스 작업을 기록합니다.
• 사용자 정의 Error 전송: 이미 포착되었거나 비즈니스에서 직접 식별한 예외를 전송합니다.

Web 세션 리플레이¶

녹화 활성화¶

SDK 초기화 후 startSessionReplayRecording() 메서드를 호출하여 세션 리플레이 녹화를 시작합니다. 사용자 로그인 후 세션 녹화 시작 등 특정 조건에서 활성화하도록 선택할 수 있습니다.

오류 관련 세션 리플레이 데이터만 수집¶

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

• 역추적 수집: 오류 발생 전 1분간의 전체 페이지 스냅샷을 기록합니다.
• 지속 녹화: 오류 발생 시점부터 세션이 종료될 때까지 계속 기록합니다.
• 지능형 보상: 독립적인 샘플링 채널로 오류 시나리오가 누락되지 않도록 보장합니다.

구성 예시¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 100,
    sessionReplaySampleRate: 0,
    sessionReplayOnErrorSampleRate: 100
  })

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()

주의 사항¶

• 세션 리플레이는 iframe, 비디오, 오디오 재생 콘텐츠를 기록하지 않습니다. Canvas는 기본적으로 수집되지 않으므로 replayCanvasEnabled를 별도로 구성해야 합니다. WebGL/WebGL2는 SDK 3.3.7부터 제공되며 RUM 메인 패키지 버전 >= 3.3.7이 필요하고, 호환되는 browser-rum-webgl 플러그인을 추가로 설치하고 등록해야 합니다. 플러그인과 메인 패키지는 동일한 SDK 릴리스 버전을 사용할 것을 권장합니다. 자세한 내용은 Canvas 녹화 사용 설명서를 참조하세요.
• 리플레이 시 폰트, 이미지 등 정적 리소스에 정상적으로 접근하려면 CORS 정책을 구성해야 할 수 있습니다.
• CSSStyleSheet 인터페이스로 CSS 규칙에 접근할 수 있어야 CSS 스타일과 마우스 호버 이벤트를 지원할 수 있습니다.

녹화 상태 확인¶

window.DATAFLUX_RUM.isRecording()을 호출하여 현재 페이지가 녹화 중인지 확인하고, 세션 리플레이 탐색기에서 해당 Session에 리플레이 데이터가 생성되었는지 확인합니다. 운영 환경에서는 비즈니스 요구에 따라 sessionReplaySampleRate를 조정하세요.