Web 애플리케이션 연동¶
이 페이지의 구성을 완료하면 Browser RUM SDK가 페이지 View, 리소스 요청, 프런트엔드 오류, 사용자 작업을 자동으로 수집하고 데이터를 Guance로 전송합니다.
App 내 WebView 페이지는 먼저 WebView 페이지 연동을 읽고, 페이지 사용 사례에 따라 초기화 방식을 선택하세요.
최초 연동 시 콘솔에서 '애플리케이션 정의 → 연동 방식 선택 → 연동 설정'을 먼저 완료한 다음 데이터 전송 검증을 수행합니다. 기본 데이터 전송에 성공한 후 필요에 따라 샘플링, 분산 추적, 세션 리플레이를 조정할 수 있습니다.
애플리케이션 정의¶
- 'RUM > 애플리케이션 목록'으로 이동하여 '새 애플리케이션'을 클릭하고 애플리케이션 유형에서 'Web'을 선택합니다.
- '애플리케이션 정의'에서 애플리케이션 이름과 애플리케이션 ID를 입력합니다. 애플리케이션이 생성되면 시스템이 클라이언트 데이터 전송에 사용할 Client Token을 자동으로 생성합니다.
- '연동 방식 선택'에서 아래 표의 방식 중 하나를 선택한 다음 '연동 설정'에 따라 해당 작업을 완료합니다.
기존 애플리케이션은 해당 구성 페이지로 바로 이동하여 애플리케이션 정보를 확인한 후 연동을 계속할 수 있습니다.
연동 방식 선택¶
| 연동 방식 | 사용 사례 | 작업 진입점 |
|---|---|---|
| Agent 자동 연동 | 코딩 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하도록 하려는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 애플리케이션 코드 저장소에서 코딩 어시스턴트에 전달 |
| 수동 연동 | 비즈니스 코드를 직접 수정하고 SDK 도입 방식과 파라미터를 구성하려는 경우 | 먼저 데이터 전송 방식을 선택한 다음 애플리케이션 형태에 맞게 SDK 연동 |
| 서버 자동 연동 | Nginx 또는 IIS로 웹사이트를 호스팅하고 서버에서 SDK를 주입하려는 경우 | 콘솔에서 수집 파라미터를 구성하고 대상 서버에서 연동 명령 실행 |
동일 페이지에서는 하나의 연동 방식을 선택합니다. 이미 RUM SDK가 있는 페이지는 기존 구성을 먼저 확인하여 중복 초기화나 중복 수집을 방지해야 합니다.
Agent 자동 연동¶
- 애플리케이션 구성 페이지에서 'Agent 자동 연동'을 선택합니다.
- '연동 설정'의 전체 프롬프트를 복사합니다. 여기에는 현재 애플리케이션 ID, DataWay 주소, 임시 인증 코드 등의 연동 정보가 포함됩니다.
- 애플리케이션 코드 저장소에서 코딩 어시스턴트를 열고 프롬프트를 붙여넣습니다. Agent는 연동 가이드에 따라 프로젝트 구조를 분석하고 기존 구성을 재사용하며 필요한 SDK 연동과 검증을 완료합니다.
- 연동 검증에 따라 실제 데이터 전송 및 저장 상황을 확인합니다.
프롬프트의 연동 가이드에는 실행 환경과 구체적인 단계가 설명되어 있습니다. 연동 정보가 준비되지 않은 경우 다음과 같이 처리합니다:
- 아직 개인 API Key를 생성하지 않음: 'API Key 생성'을 클릭한 후 프롬프트를 다시 복사하세요. 해당 권한이 없으면 워크스페이스 관리자에게 권한 부여를 요청하세요.
- 임시 인증 코드가 준비되지 않음: 먼저 Agent가 프로젝트를 분석하도록 하고 필요한 정보를 보완한 후 연동을 계속할 수 있습니다.
수동 연동¶
수동 연동은 두 단계로 나뉩니다. 먼저 데이터 전송 방식을 선택한 다음 NPM 또는 CDN 등 SDK 도입 방식을 선택합니다.
| 데이터 전송 방식 | 권장 사용 사례 | 초기화 파라미터 |
|---|---|---|
| 공용 DataWay 사용 | 일반적으로 우선 선택하며, Guance에서 데이터 수신 서비스를 제공합니다 | applicationId, site, clientToken |
| 로컬 환경 배포 | DataKit을 직접 배포 및 관리해야 하거나 현재 워크스페이스에서 공용 DataWay 주소를 제공하지 않는 경우 | applicationId, datakitOrigin |
두 전송 방식 중 하나만 선택합니다. site와 clientToken은 공용 DataWay에 사용하고, datakitOrigin은 로컬 환경 배포에 사용하므로 동일한 초기화 구성에 동시에 입력하지 마세요.
전송 설정 준비¶
- '수동 연동'에서 '공용 DataWay 사용'을 선택합니다.
- 현재 애플리케이션의 연동 설정에서
applicationId,site,clientToken을 복사합니다. 콘솔에서 제공하는 현재 사이트 주소를 사용해야 하며, 콘솔 로그인 주소나 다른 사이트의 주소를site로 사용하지 마세요. - SDK 연동 시 다음 구성을 유지하며 DataKit을 설치하거나 RUM 수집기를 별도로 구성할 필요가 없습니다.
- DataKit을 설치하고 RUM 수집기를 활성화합니다.
- 사용자 브라우저가 있는 네트워크에서 DataKit의 데이터 전송 주소에 액세스할 수 있는지 확인하고, 필요에 따라 IP 지리 정보 라이브러리 설치를 통해 사용자 IP에 해당하는 지리 정보를 확인합니다.
- '수동 연동'에서 '로컬 환경 배포'를 선택하고
datakitOrigin을 실제 DataKit 수신 주소로 구성합니다. HTTPS 페이지는 액세스 가능한 HTTPS 수신 주소를 사용하여 브라우저에서 요청이 차단되지 않도록 해야 합니다. - SDK 연동 시
site와clientToken을 제거하고 다음 구성을 사용합니다.
서버 자동 연동¶
Nginx 또는 IIS를 통해 웹사이트 HTML 페이지에 RUM SDK를 주입합니다. 애플리케이션 코드를 수정할 필요는 없지만 대상 서버의 구성 및 명령 실행 권한이 필요합니다.
전제 조건¶
- Web 애플리케이션이 생성되었고 대상 서버의 구성 및 명령 실행 권한이 있어야 합니다.
- 페이지에 주입 가능한
<head>태그가 포함되어 있어야 하며, 동일 페이지에는 하나의 RUM SDK 연동 방식만 유지하여 중복 수집을 방지해야 합니다. - 브라우저가 SDK 리소스와 데이터 전송 주소에 액세스할 수 있어야 합니다. CSP를 사용하는 경우 CSP 보안 정책에 따라 허용 범위를 구성하세요.
| 서버 | 환경 요구 사항 및 작업 영향 |
|---|---|
| Nginx | Linux Nginx 1.9.4+, http_sub_module, Bash 및 curl; root 또는 sudo로 실행. 연동 설정 변경 시 Nginx를 다시 로드합니다 |
| IIS | 64비트 Windows, IIS 7.5+, URL Rewrite 2.x, 정적 리소스 읽기 권한 및 전용 애플리케이션 풀; 관리자 권한으로 PowerShell 5.1+ 실행. 활성화, 비활성화, 업데이트, 롤백 시 애플리케이션 풀이 재활용되어 프로세스 내 세션이 유실될 수 있습니다 |
연동 구성¶
- Web 애플리케이션 구성 페이지의 '연동 방식 선택'에서 '서버 자동 연동'을 선택합니다.
- '애플리케이션 연결'에서 OpenWay 또는 DataKit을 선택하고 전송 주소, 서비스 이름, 환경, 애플리케이션 버전을 확인합니다. 애플리케이션 버전은 비즈니스 버전을 표시하는 데 사용되며 SDK를 업그레이드하지 않습니다.
- 'SDK 소스 및 로드'에서 리소스 소스와 로드 방식을 확인합니다.
- '수집 내용'에서 세션 샘플링 비율, 오류 세션 보상 샘플링 비율, 사용자 상호작용 수집을 설정합니다. 필요에 따라 세션 리플레이를 활성화하고 리플레이 샘플링 비율, 오류 리플레이 보상 샘플링 비율, 프라이버시 수준을 구성합니다. 리플레이는 먼저 세션 샘플링을 거친 후 리플레이 샘플링을 거칩니다.
- '설치 환경'에서 Nginx 또는 IIS를 선택하고 현재 환경 요구 사항을 읽습니다. 필요에 따라 '고급 연동 설정'을 펼칩니다.
- '설치 명령 실행'에서 현재 구성으로 생성된 명령을 복사하여 대상 서버에서 실행합니다. 자동 검색된 사이트를 사용하는 경우 터미널 안내에 따라 연동할 사이트를 선택합니다.
명령에 구성이 포함되어 있으므로 파일을 별도로 다운로드할 필요가 없습니다. 보관하거나 수동으로 업데이트해야 하는 경우 rumable.toml을 다운로드할 수 있습니다. 명령과 구성에는 Client Token이 포함되므로 안전하게 보관해야 합니다.
검증 및 업데이트¶
명령을 실행한 후 서버 실행 결과를 먼저 확인한 다음 연동 검증에 따라 웹사이트의 SDK가 정상적으로 실행되고 데이터가 저장되었는지 확인합니다. 설치 성공 또는 페이지의 HTTP 200 응답만으로는 데이터 수집 성공을 입증할 수 없습니다.
데이터가 수신되지 않으면 활성화된 사이트와 경로에 액세스했는지, SDK가 CSP에 의해 차단되었는지, 전송 주소에 접근 가능한지, 세션이 샘플링되었는지 확인합니다. 페이지가 이미 NPM 또는 CDN을 통해 SDK에 연동되어 있다면 먼저 중복 연동을 해결해야 합니다.
수집 파라미터를 수정한 후 연동 명령을 다시 생성하여 대상 서버에서 실행합니다. 콘솔에서 구성만 저장하거나 복사하면 서버의 주입 구성이 자동으로 업데이트되지 않습니다. 다운로드한 rumable.toml을 수정한 경우에도 서버에서 다시 적용해야 합니다.
SDK 파라미터의 의미는 파라미터 구성을, 샘플링 규칙은 샘플링 구성을 참조하세요.
SDK 수동 연동¶
다음 예시는 기본적으로 공용 DataWay를 사용합니다. 로컬 환경 배포를 사용하는 경우 전송 설정 준비에 따라 전송 파라미터를 교체하세요.
애플리케이션 형태에 따라 아래 표의 연동 진입점을 선택합니다. NPM, CDN은 페이지에서 SDK를 로드하는 방법을 결정하고, 공용 DataWay, 로컬 DataKit은 데이터를 어디로 전송할지 결정하므로 각각 구성합니다.
| 애플리케이션 형태 | 권장 진입점 | 설명 |
|---|---|---|
| Webpack, Vite, Rollup 등 빌드 도구 사용 | NPM 연동 | 권장 방식으로 버전 관리와 필요한 기능만 연동하기에 용이하지만 초기화 전 요청과 오류를 놓칠 수 있음 |
| 프런트엔드 빌드 프로세스 없음 | CDN 비동기 로드 | 페이지 구문 분석을 차단하지 않지만 초기화 전 요청과 오류를 놓칠 수 있음 |
| 페이지 오류와 요청을 최대한 이른 시점에 수집해야 함 | CDN 동기 로드 | 최대한 이른 시점에 초기화하지만 페이지 로드 시간을 점유함 |
| 기본 RUM만 필요하고 프런트엔드 번들 크기를 중시함 | 슬림 RUM SDK | 일반 RUM 수집은 유지하되 Session Replay와 전송 압축은 포함하지 않음 |
| React, Vue, Angular 단일 페이지 애플리케이션 | 프런트엔드 프레임워크 플러그인 연동 | Router View와 프레임워크 오류를 자동으로 관리 |
| Next.js, Nuxt | SSR 프레임워크에서 연동 | 서버 측과 브라우저 환경을 구분하여 View 중복 방지 |
| Electron | Electron 애플리케이션 연동 | renderer process에서만 초기화 |
| App 내 WebView 페이지 | WebView 페이지 연동 | 일반 연동과 App 내 임베디드 전용 시나리오를 구분하고, 호스트 측에서 각 플랫폼에 맞게 Bridge 구성 |
NPM 연동¶
프런트엔드 프로젝트에 SDK를 설치하고 가져옵니다:
프로젝트에서 SDK를 초기화합니다:
import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_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_DATAWAY_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_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-app",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
trackUserInteractions: true
})
})
</script>
DOM만 기록하는 세션 리플레이¶
Browser SDK 3.3.25부터 DOM 리플레이 스크립트를 로드하여 RUM 이벤트를 수집하고 DOM을 녹화할 수 있습니다.
Canvas 2D 또는 WebGL 녹화가 필요한 페이지에서는 전체 RUM 번들을 사용하십시오. 한 페이지에는 하나의 번들만 로드합니다. 초기화 API와 리플레이 샘플링 설정은 동일합니다.
슬림 RUM SDK¶
RUM SDK 3.3.3부터 슬림 버전을 제공합니다. 슬림 버전은 전체 버전과 동일한 초기화 방식을 사용하며 View, Resource, Long Task, Error, Action, 사용자 및 전역 Context, 사용자 정의 이벤트, 분산 추적 등 일반 RUM 기능을 지원하여 페이지 기록이 필요 없고 프런트엔드 번들 크기를 줄이고자 하는 애플리케이션에 적합합니다.
NPM 연동¶
일반 RUM 패키지를 동일 버전의 슬림 패키지로 교체합니다:
import { datafluxRum } from "@cloudcare/browser-rum-slim"
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_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_DATAWAY_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 파일을 전체 버전으로 다시 전환하세요. 기타 기본 초기화 파라미터는 계속 사용할 수 있습니다.
연동 검증¶
다음 단계는 Web SDK 독립 전송에 사용됩니다. App WebView Bridge 모드는 WebView 데이터 검증을 직접 참조하세요.
- SDK가 연동된 페이지를 열고 페이지 이동, 버튼 클릭, API 요청을 한 번씩 수행합니다.
- 브라우저 개발자 도구의 Network에서
/v1/write/rum을 필터링하여 성공한 전송 요청이 있는지 확인합니다. - Console을 확인하여
Application ID is not configured,datakitOrigin or site is not configured등의 초기화 오류가 없는지 확인합니다. - 'RUM > 애플리케이션 목록'으로 이동하여 해당 Web 애플리케이션을 열고, 탐색기에서 연동 구성의
service,env,version으로 필터링하여 View, Resource 또는 Action 데이터가 수신되었는지 확인합니다.
View 데이터가 보이면 기본 연동이 성공한 것입니다
Error, Resource, Action은 페이지에서 해당 이벤트가 실제로 발생한 후에만 나타납니다. 데이터가 없으면 현재 Session이 sessionSampleRate에 해당하는지 먼저 확인한 후 FAQ를 참조하세요.
SDK 초기화 결과 가져오기¶
Web RUM 전체 버전과 슬림 버전 모두 Browser SDK 3.3.25부터 초기화 콜백을 지원합니다.
기존 init() 호출에 onInitSuccess와 onInitError를 지정합니다. CDN에서 SDK를 비동기로 로드할 때는 onReady() 안에서 init()을 호출합니다.
SDK는 설정 검증과 필요한 세션 저장소 확인을 마친 뒤 onInitSuccess를 호출합니다. remoteConfiguration을 켜면 원격 설정을 먼저 처리합니다. 전체 버전에서 압축 전송을 사용하면 성공 콜백은 압축 Worker가 준비될 때까지 기다립니다. View 자동 수집은 콜백이 호출되기 전에 시작될 수 있습니다. 슬림 버전과 JSON 형식으로 전송하는 전체 버전은 압축 Worker를 기다리지 않습니다.
다음 예시는 공용 DataWay를 사용하며, initOptions를 현재 RUM 인스턴스의 init(initOptions)에 전달하면 됩니다.
const initOptions = {
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
remoteConfiguration: true,
onInitSuccess(result) {
console.log("RUM 初始化成功", result.remoteConfiguration)
if (result.remoteConfiguration === "fallback") {
console.warn("RUM 已使用本地配置启动", result.remoteConfigurationError.code)
}
},
onInitError(error) {
console.error("RUM 初始化失败", error.code, error.message)
}
}
result.remoteConfiguration |
의미 |
|---|---|
disabled |
원격 구성이 비활성화되어 SDK가 로컬 구성으로 초기화를 완료했습니다. |
applied |
SDK가 유효한 원격 응답을 처리했습니다. 빈 구성이 반환된 경우에도 로컬 구성은 계속 적용됩니다. |
fallback |
원격 요청 또는 응답 구문 분석에 실패하여 SDK가 로컬 구성으로 초기화를 완료했습니다. remoteConfigurationError에는 code와 message가 포함되며, HTTP 오류에는 status도 포함됩니다. |
원격 요청 제한 시간은 10초입니다. 시간 초과, 네트워크 오류, 200이 아닌 응답 또는 응답 형식 오류가 발생하면 로컬 구성으로 폴백됩니다. 로컬 구성으로도 SDK를 시작할 수 없으면 이번 호출에서는 onInitError만 트리거됩니다.
각 init() 호출에서는 최대 하나의 결과 콜백이 트리거됩니다. init()은 undefined를 반환하며, 콜백은 반환 전에 동기적으로 실행될 수 있습니다. View를 수동으로 관리하는 경우 onInitSuccess 안에서 startView()를 호출해 첫 번째 View를 생성할 수 있습니다. Web SDK가 직접 전송하는 경우 연동 검증에 따라 브라우저의 전송 요청을 확인하고 해당 Web 애플리케이션에서 View를 확인하세요. App WebView Bridge를 사용하는 경우 App SDK가 데이터를 전송하므로 WebView 데이터 검증에 따라 해당 App 애플리케이션에서 View를 확인하세요.
error.code |
처리 방법 |
|---|---|
invalid_configuration, invalid_plugins |
로컬 또는 원격 재정의 후의 파라미터와 플러그인 설정을 확인하고 수정한 후 init()을 다시 호출합니다. |
storage_unavailable |
브라우저 쿠키, localStorage, 세션 저장소 구성을 확인하고 저장소가 복구된 후 다시 시도합니다. |
worker_initialization_failed |
전체 버전에서 압축 Worker를 시작하지 못했거나 시작 시간이 초과되었습니다. SDK는 onInitError를 한 번 호출합니다. error.message에 표시된 원인에 따라 Worker URL(workerUrl), 네트워크 연결 또는 콘텐츠 보안 정책(CSP)을 확인하세요. 문제를 해결한 뒤 페이지를 새로 고쳐 SDK를 다시 초기화하세요. SDK는 현재 페이지에서 이후의 init() 호출을 무시합니다. |
already_initialized |
이번 호출은 거부되었으며, 첫 번째 호출이 자체 콜백을 유지합니다. silentMultipleInit은 콘솔 안내만 제어합니다. |
initialization_ignored |
현재 인스턴스가 초기화를 Synthetics에서 주입한 인스턴스에 위임합니다. |
sdk_disabled, initialization_failed |
SDK 생성 또는 시작 시 예외가 발생했습니다. 원인을 파악하고 수정한 후 페이지를 새로 고치세요. |
자주 사용하는 선택적 구성¶
기본 데이터가 확인된 후 필요에 따라 다른 기능을 활성화하세요:
| 목표 | 구성 또는 API | 문서 |
|---|---|---|
| 프런트엔드와 백엔드 분산 추적 연결 | allowedTracingUrls, traceType |
분산 추적 구성 |
| 익명 방문자별 API 요청 빈도 제한 | visitorId, resetVisitorId() |
방문자 식별자 Visitor ID |
| 수집 비율 제어 | sessionSampleRate, startSession() |
샘플링 구성 |
| 오류 세션 이벤트만 수집 | sessionOnErrorSampleRate |
오류 세션 보상 샘플링 |
| 세션 리플레이 활성화 | startSessionReplayRecording() |
Web 세션 리플레이 |
| 전송 데이터 압축 | compressIntakeRequests |
데이터 압축 |
| SPA Router View 자동 관리 | plugins |
프런트엔드 프레임워크 플러그인 연동 |
| WebGL/WebGL2 기록 | plugins, Canvas 자동 기록 |
Canvas 기록 사용 설명서 |
| 로그인 사용자 식별 | setUser() |
사용자 정의 사용자 식별자 |
| 비즈니스 필드 또는 이벤트 추가 | Global Context, addAction(), addError() |
사용자 정의 데이터 및 이벤트 |
분산 추적 구성(선택 사항)¶
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_DATAWAY_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_DATAWAY_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도 올바르게 구성해야 합니다.
파라미터 구성¶
초기화 파라미터¶
| 파라미터 | 유형 |
필수 여부 |
기본값 |
설명 |
|---|---|---|---|---|
applicationId |
String | 예 | Guance에서 생성한 애플리케이션 ID입니다. | |
datakitOrigin |
String | 로컬 환경 배포 시 | DataKit 데이터 전송 주소이며 형식은 프로토콜(:// 포함) + 도메인 또는 IP + 선택적 포트입니다. 예: https://datakit.example.com. |
|
clientToken |
String | 공용 DataWay 사용 시 | 공용 DataWay 데이터 전송 Token이며 Guance 콘솔에서 가져옵니다. | |
site |
String | 공용 DataWay 사용 시 | 공용 DataWay 데이터 전송 주소이며 Guance 콘솔에서 가져옵니다. | |
env |
String | 아니요 | Web 애플리케이션의 현재 환경입니다. 예: prod: 프로덕션 환경, gray: 그레이 환경, pre: 사전 릴리스 환경, common: 일상 환경, local: 로컬 환경. | |
version |
String | 아니요 | Web 애플리케이션의 버전 번호입니다. | |
service |
String | 아니요 | 현재 애플리케이션의 서비스 이름이며 기본값은 browser이고 사용자 정의 구성이 지원됩니다. |
|
sessionSampleRate |
Number | 아니요 | 100 |
메트릭 데이터 수집 비율:100은 전체 수집, 0은 수집하지 않음을 의미합니다. |
sessionOnErrorSampleRate |
Number | 아니요 | 0 |
오류 세션 보상 샘플링 비율: 세션이 sessionSampleRate에 의해 샘플링되지 않았더라도 세션 중 오류가 발생하면 이 비율에 따라 수집합니다. 이러한 세션은 오류 발생 시점부터 이벤트 기록을 시작하여 세션 종료까지 계속 기록합니다. SDK 버전 요구 사항 >= 3.2.19 |
sessionReplaySampleRate |
Number | 아니요 | 100 |
Session Replay 데이터 수집 비율:100은 전체 수집, 0은 수집하지 않음을 의미합니다. |
sessionReplayOnErrorSampleRate |
Number | 아니요 | 0 |
Session Replay 오류 세션 리플레이 보상 샘플링 비율: 세션이 sessionReplaySampleRate에 의해 샘플링되지 않았더라도 세션 중 오류가 발생하면 이 비율에 따라 수집합니다. 이러한 리플레이는 오류 발생 전 최대 1분 동안의 이벤트를 기록하고 세션 종료까지 계속 기록합니다. SDK 버전 요구 사항 >= 3.2.19 |
trackSessionAcrossSubdomains |
Boolean | 아니요 | false |
동일 도메인의 하위 도메인 간에 캐시를 공유합니다. |
usePartitionedCrossSiteSessionCookie |
Boolean | 아니요 | false |
분할 보안 교차 사이트 세션 쿠키를 활성화할지 여부 상세 |
useSecureSessionCookie |
Boolean | 아니요 | false |
보안 세션 쿠키를 사용합니다. 이 경우 안전하지 않은(HTTPS가 아닌) 연결에서 전송되는 RUM 이벤트가 비활성화됩니다. |
traceType |
TraceType |
아니요 | TraceType.DDTRACE(런타임 값 ddtrace) |
분산 추적 도구 유형을 구성합니다. NPM 연동은 TraceType 열거형을 사용하고, CDN 연동은 해당 런타임 문자열을 사용합니다. 현재 DDTRACE(ddtrace), ZIPKIN_MULTI_HEADER(zipkin), ZIPKIN_SINGLE_HEADER(zipkin_single_header), W3C_TRACEPARENT(w3c_traceparent), W3C_TRACEPARENT_64(w3c_traceparent_64bit), SKYWALKING_V3(skywalking_v3), JAEGER(jaeger)를 지원합니다.❗️ 1. OpenTelemetry는 zipkin_single_header, w3c_traceparent, zipkin, jaeger 4가지 유형을 지원합니다.2. 이 구성의 적용은 allowedTracingUrls에 의존합니다.3. 해당 유형을 구성할 때 API 서비스에 대응하는 Access-Control-Allow-Headers를 설정해야 합니다. 자세한 내용은 APM에서 RUM을 연결하는 방법을 참조하세요. |
traceId128Bit |
Boolean | 아니요 | false |
traceID를 128비트 모드로 생성할지 여부이며 traceType에 대응합니다. 현재 zipkin, jaeger를 지원합니다. |
allowedTracingUrls |
Array | 아니요 | [] |
Trace Header 주입을 허용할 요청 URL 일치 목록입니다. 배열 항목은 전체 URL, 정규식, 일치 함수 또는 match와 traceType을 포함하는 객체일 수 있습니다. 예: ["https://api.example.com/xxx", /https:\/\/.*\.my-api-domain\.com\/xxx/, (url) => url.includes("/api/")]. |
allowTraceHeaderWithoutSession |
Boolean | 아니요 | false |
현재 RUM Session이 샘플링에 해당하지 않을 때도 allowedTracingUrls에 해당하는 XHR 및 Fetch 요청에 Trace Header를 주입할지 여부입니다. 활성화해도 Session을 생성하지 않으며 샘플링되지 않은 Session의 RUM 데이터도 전송하지 않습니다. |
allowedTracingOrigins |
Array | 아니요 | [] |
더 이상 사용되지 않으며 이전 버전 구성과의 호환성을 위해서만 유지됩니다. 신규 연동에서는 allowedTracingUrls를 사용하세요. 둘 다 구성된 경우 allowedTracingUrls가 이 구성을 덮어씁니다. |
trackUserInteractions |
Boolean | 아니요 | false |
사용자 행동 수집을 활성화할지 여부입니다. |
enablePrivacyForActionName |
Boolean | 아니요 | false |
자동 Action 이름이 DOM 프라이버시 수준을 따르도록 할지 여부입니다. 활성화하면 마스킹된 이름은 고정 자리표시자를 사용하고, 숨겨진 요소의 클릭은 자동 Action을 생성하지 않습니다. 명시적으로 구성된 Action 이름 속성은 계속 사용할 수 있습니다. SDK 버전 요구 사항 >= 3.3.14, 자세한 내용은 자동 Action 이름 보호를 참조하세요. |
trackViewsManually |
Boolean | 아니요 | false |
SDK 자동 View를 비활성화하고 애플리케이션에서 startView()를 호출해 수동으로 View를 시작할지 여부입니다. 프레임워크 Router 플러그인이 이 구성을 자동으로 관리하므로 비즈니스에서 중복 설정할 필요가 없습니다. 자세한 내용 |
plugins |
Array | 아니요 | [] |
RUM 플러그인을 등록하며 init() 시 전달해야 합니다. 프레임워크 플러그인은 React, Vue, Angular, Next.js, Nuxt의 라우터 View와 프레임워크 오류를 수집할 수 있습니다. SDK 버전 요구 사항 >= 3.3.6, 자세한 내용은 프런트엔드 프레임워크 플러그인 연동을 참조하세요. WebGL Replay는 SDK 3.3.7부터 제공되며 RUM 메인 패키지 버전 >= 3.3.7이 필요하고, 플러그인과 메인 패키지에 동일한 SDK 릴리스 버전을 사용할 것을 권장합니다. 자세한 내용은 Canvas 기록 사용 설명서를 참조하세요. |
enableExperimentalFeatures |
Array | 아니요 | [] |
실험 기능을 활성화합니다. ["track_websockets"]를 구성하면 네이티브 WebSocket 연결 수준 Resource를 수집할 수 있습니다. SDK 버전 요구 사항 >= 3.3.6. 자세한 내용 |
actionNameAttribute |
String | 아니요 | 버전 요구 사항: >3.1.2. 요소에 사용자 정의 속성을 추가하여 작업 이름을 지정합니다. 구체적인 사용 방법은 자세한 내용을 참조하세요. |
|
beforeSend |
Function(event, context):Boolean | 아니요 | 버전 요구 사항: >3.1.2. 데이터 차단 및 데이터 수정, 자세한 내용 |
|
storeContextsToLocal |
Boolean | 아니요 | 버전 요구 사항: >3.1.2. 사용자 정의 데이터를 로컬 localStorage에 캐시할지 여부입니다. 예: setUser, addGlobalContext API로 추가한 사용자 정의 데이터. |
|
storeContextsKey |
String | 아니요 | 버전 요구 사항: >3.1.18. localStorage에 저장할 key를 정의합니다. 기본값은 비어 있으며 자동 생성됩니다. 이 파라미터는 주로 동일 도메인에서 서로 다른 하위 경로가 store를 공유하는 문제를 구분하기 위한 것입니다. 사용자 식별자와 세션 경계 구성은 페이지 새로 고침 및 로컬 저장소를 참조하세요. |
|
compressIntakeRequests |
Boolean | 아니요 | RUM 데이터 요청 내용을 압축하여 대량 데이터 전송 시 대역폭 사용량을 줄이고 전송 데이터 요청 수를 줄일 수 있습니다. 압축은 WebWorker 스레드에서 수행됩니다. CSP 보안 정책은 CSP 보안을 참조하세요. SDK 버전 요구 사항 >= 3.2.0. datakit 버전 요구 사항 >=1.60. 배포 플랜 요구 사항 >= 1.96.178 |
|
workerUrl |
String | 아니요 | Session Replay와 compressIntakeRequests 데이터 압축은 모두 WebWorker 스레드에서 수행되므로 기본적으로 CSP 보안 액세스를 활성화한 경우 worker-src blob:을 허용해야 합니다. 이 구성은 직접 호스팅하는 Worker 주소를 추가할 수 있습니다. CSP 보안 정책은 CSP 보안을 참조하세요. SDK 버전 요구 사항 >= 3.2.0. |
|
remoteConfiguration |
Boolean | 아니요 | 데이터 수집의 원격 구성 기능을 활성화할지 여부이며 기본값은 비활성화입니다. 원격 구성 기능을 사용하면 새 버전을 배포하지 않고도 데이터 수집 구성 항목을 동적으로 수정할 수 있습니다. 예: 원격 구성에서 샘플링 비율, 사용자 행동 수집 활성화 여부 등을 변경할 수 있습니다. 원격 구성 기능을 사용하려면 Guance 콘솔에서 환경 변수 설정을 활성화해야 합니다. SDK 버전 요구 사항 >= 3.2.20. datakit 버전 요구 사항 >=1.60. Guance 콘솔에서 환경 변수 기능을 활성화하는 방법 |
|
onInitSuccess |
function |
아니요 | SDK 3.3.25 이상에서 지원됩니다. 초기화 성공 시 호출되며, 파라미터에는 원격 구성 처리 결과가 포함됩니다. 자세한 내용은 초기화 결과를 참조하세요. |
|
onInitError |
function |
아니요 | SDK 3.3.25 이상에서 지원됩니다. 이번 초기화 실패 또는 호출 거부 시 트리거되며, 파라미터에는 code와 message가 포함됩니다. 자세한 내용은 오류 코드를 참조하세요. |
|
replayCanvasWorkerUrl |
string |
아니요 | canvas snapshot 인코딩 전용 worker 주소이며 workerUrl을 대체하지 않습니다. 이 구성은 직접 호스팅하는 worker 주소를 추가할 수 있습니다. CSP 보안 정책은 CSP 보안을 참조하세요. SDK 버전 요구 사항 >= 3.3.0. |
|
replayCanvasEnabled |
boolean |
아니요 | false |
canvas 기록을 활성화할지 여부입니다. 활성화하지 않으면 canvas를 수집하지 않습니다. SDK 버전 요구 사항 >= 3.3.0. |
replayCanvasMode |
'manual' \| 'auto' |
아니요 | auto |
canvas 기록 모드입니다. manual은 snapshotCanvas(canvas)를 수동으로 호출해야 하며, auto는 자동 기록입니다. |
replayCanvasSampling |
number \| 'all' |
아니요 | 2 |
replayCanvasMode: 'auto'에서만 적용됩니다. 양수는 자동 snapshot 경로를 선택하며 2부터 시작하는 것이 좋습니다. 값 자체는 Canvas 2D의 수집 빈도를 제어하지 않습니다. 'all'은 Canvas 2D가 더 높은 복원도의 command capture를 시도하도록 하며, 복잡한 시나리오에서는 여전히 snapshot으로 폴백될 수 있습니다. WebGL 플러그인은 항상 예산이 적용된 픽셀 스냅샷을 사용합니다. |
replayCanvasAutoInterval |
number |
아니요 | 250 |
각 Canvas의 자동 snapshot 목표 간격(밀리초)입니다. 여러 Canvas는 공정하게 순환하며, 실제 주기는 cooldown, backoff, 페이지 가시성 및 전역 런타임 예산의 제한도 받습니다. |
replayCanvasQuality |
'low' \| 'medium' \| 'high' \| number |
아니요 | 0.4 |
Canvas snapshot 인코딩 품질입니다. 문자열 프리셋은 sampling과 자동 스케줄링 예산도 함께 조정합니다. 이미지 품질만 변경하려면 0에서 1 사이의 숫자를 전달하세요. |
replayCanvasAutoCooldown |
number |
아니요 | 250 |
동일 Canvas 자동 snapshot의 최소 쿨다운 시간(밀리초)입니다. |
replayCanvasAutoUnchangedBackoff |
number |
아니요 | 3000 |
경량 서명이 계속 변경되지 않을 때 다음 전체 인코딩 검증을 트리거하는 간격(밀리초)입니다. 그동안에도 제한적이고 적응적인 주기로 변경을 감지합니다. |
replayCanvasAutoFailureBackoff |
number |
아니요 | 5000 |
자동 수집 실패 후 백오프 시간(밀리초)입니다. |
replayCanvasAutoMaxPerRun |
number |
아니요 | 2 |
한 번의 자동 스케줄링에서 처리할 최대 Canvas 수입니다. |
replayCanvasFlushImmediately |
boolean |
아니요 | manual: trueauto: false |
Canvas 프레임이 replay에 성공적으로 진입한 후 우선적으로 flush할지 여부입니다. |
silentMultipleInit |
boolean |
아니요 | 중복 초기화에 대한 콘솔 안내를 비활성화할지 여부입니다. 이미 구성된 onInitError는 계속 already_initialized를 수신합니다. |
low, medium, high 문자열 프리셋을 사용하지 않는 경우 Canvas 자동 스케줄링 기준은 sampling
2, Canvas별 목표 interval 250 ms, cooldown 250 ms, unchanged backoff 3000 ms,
failure backoff 5000 ms, 라운드당 최대 2개의 Canvas입니다. 문자열 프리셋은 이러한
예산과 인코딩 품질을 함께 대체합니다. 다중 Canvas는 공정 순환과 전역 수집 예산의 제한도 받습니다.
명시적인 개별 구성은 프리셋의 해당 값을 덮어씁니다. 전체 preset 매트릭스는
Canvas 기록 사용 설명서를 참조하세요.
위의 고빈도 스케줄링 기준은 Canvas 2D에 적용됩니다. WebGL 플러그인은 interval/cooldown을 명시적으로 구성하지 않은 경우 더 보수적인 GPU readback 주기를 계속 사용하며, 개별 항목을 명시적으로 구성한 경우에만 각각 재정의됩니다.
공용 DataWay 사이트 주소¶
site는 공용 데이터 수신 주소를 지정하는 데 사용됩니다. 현재 애플리케이션 연동 설정에 있는 주소를 우선 복사하세요. 아래 표는 사이트를 확인하는 용도이며, 로컬 환경 배포를 사용하는 경우 datakitOrigin만 구성하면 됩니다.
| 노드 이름 | 주소 |
|---|---|
| 중국 리전 1(항저우) | https://rum-openway.guance.com |
| 중국 리전 2(닝샤) | https://aws-openway.guance.com |
| 중국 리전 4(광저우) | https://cn4-openway.guance.com |
| 중국 리전 6(홍콩) | https://cn6-openway.guance.one |
| 국제 리전 1(오리건) | https://us1-openway.guance.com |
| 유럽 리전 1(프랑크푸르트) | https://eu1-openway.guance.one |
| 아시아 태평양 리전 1(싱가포르) | https://ap1-openway.guance.one |
| 아시아 태평양 리전 2(싱가포르) | https://ap2-openway.guance.com |
| 아프리카 리전 1(남아프리카) | https://za1-openway.guance.com |
| 인도네시아 리전 1(자카르타) | https://id1-openway.guance.com |
런타임 Session 제어¶
RUM SDK 3.3.6에 startSession()이 추가되었습니다. 호출하면 현재 Session이 즉시 종료되고 현재
샘플링 구성에 따라 Session이 다시 시작되므로 다음 사용자 상호작용을 기다릴 필요가 없습니다:
런타임 sessionSampleRate를 동시에 재정의할 수도 있습니다:
샘플링 비율은 0에서 100 사이여야 합니다. 이 재정의 값은 이번 및 이후 자동으로 이어서 생성되는 Session에 사용됩니다. 전체 RUM 패키지와 슬림 RUM 패키지 모두 이 API를 지원합니다. 자세한 의미와 사용 사례는 런타임 Session 다시 시작을 참조하세요.
필요에 따라 고급 기능 활성화¶
오류 세션 이벤트만 수집¶
버전 요구 사항
SDK 버전 요구 사항 >= 3.2.19.
sessionOnErrorSampleRate는 일반 샘플링에 해당하지 않는 오류 세션을 보상하는 데 사용됩니다. 세션에서 오류가 발생하고 보상 샘플링에 해당하면 SDK는 오류 발생 시점부터 세션 종료까지 이벤트를 기록합니다.
다음 예시는 일반 세션 샘플링을 비활성화하고 오류 세션 보상 샘플링 비율을 100%로 설정합니다.
구성 방안¶
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
sessionSampleRate: 0,
sessionOnErrorSampleRate: 100
})
위 예시는 공용 DataWay를 사용합니다. 로컬 환경 배포 시 기본 연동 예시에 따라 전송 주소 필드를 교체하세요.
데이터 압축¶
페이지에 대량의 정적 리소스(예: JS, CSS, 이미지)가 포함되어 있거나 샘플링 비율이 높으면 RUM 전송 데이터가 많아질 수 있습니다.
compressIntakeRequests: true를 설정하면 SDK가 Web Worker에서 deflate를 사용하여 전송 데이터를 압축해 요청 크기와 요청 수를 줄입니다.
구성 예시¶
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
compressIntakeRequests: true
})
주의 사항¶
- 데이터 압축 로직은 Web Worker에서 실행됩니다. CSP 보안 정책을 활성화한 경우
worker-src에서blob:을 허용해야 합니다. 자세한 내용은 CSP 보안 정책 설명을 참조하세요. - SDK는
workerUrl구성 항목을 통해 자체 호스팅 Worker 주소를 지정할 수 있습니다. - 이 기능을 사용하는 SDK 버전은 >= 3.2여야 합니다.
사용자 정의 데이터 및 이벤트¶
비즈니스 목표에 따라 해당 API를 선택하고 CDN, NPM 연동 예시 및 파라미터 설명을 확인하세요:
- 사용자 작업 추적: 클릭 자동 수집, Action 이름 정의, 사용자 정의 Action 추가.
- 사용자 정의 사용자 식별자: 로그인 후 사용자를 설정하고, 로그아웃하거나 계정을 전환할 때 사용자를 정리합니다.
- 전역 Context: 모든 후속 RUM 이벤트에 안정적인 비즈니스 차원을 추가합니다.
- 사용자 정의 Action 추가: 페이지 클릭으로 표현할 수 없는 비즈니스 작업을 기록합니다.
- 사용자 정의 Error 전송: 이미 포착되었거나 비즈니스에서 능동적으로 식별한 예외를 전송합니다.
Web 세션 리플레이¶
전제 조건
Session Replay가 포함된 전체 RUM 패키지를 사용하세요. 슬림 RUM 패키지에는 세션 리플레이 기능이 포함되어 있지 않습니다.
기록 활성화¶
SDK 초기화 후 startSessionReplayRecording() 메서드를 호출하여 세션 리플레이 기록을 활성화합니다. 사용자 로그인 후 세션 기록 활성화와 같이 특정 조건에서 활성화할 수 있습니다.
오류 관련 세션 리플레이 데이터만 수집¶
버전 요구 사항
SDK 버전 요구 사항 >= 3.2.19.
sessionReplayOnErrorSampleRate는 일반 리플레이 샘플링에 해당하지 않는 오류 세션을 보상하는 데 사용됩니다. 세션에서 오류가 발생하고 보상 샘플링에 해당하면 오류 발생 전 최대 1분간의 리플레이 데이터를 소급하여 기록할 수 있으며, 세션 종료까지 계속 기록합니다.
다음 예시는 모든 RUM 세션을 수집하고 일반 리플레이 샘플링을 비활성화하며, 오류 세션 리플레이 보상 샘플링 비율을 100%로 설정하고 기록 API를 호출합니다. 세션 리플레이는 여전히 RUM 세션 샘플링 결과의 제약을 받습니다. 구체적인 규칙은 샘플링 구성을 참조하세요.
구성 예시¶
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
sessionSampleRate: 100,
sessionReplaySampleRate: 0,
sessionReplayOnErrorSampleRate: 100
})
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
주의 사항¶
- 세션 리플레이는 iframe, 비디오, 오디오의 재생 내용을 기록하지 않습니다. Canvas는 기본적으로 수집하지 않으며
replayCanvasEnabled를 별도로 구성해야 합니다. WebGL/WebGL2는 SDK3.3.7부터 제공되며 RUM 메인 패키지 버전>= 3.3.7이 필요하고, 호환되는browser-rum-webgl플러그인을 추가로 설치 및 등록해야 합니다. 플러그인과 메인 패키지에 동일한 SDK 릴리스 버전을 사용할 것을 권장합니다. 자세한 내용은 Canvas 기록 사용 설명서를 참조하세요. - 리플레이 시 정적 리소스(예: 글꼴, 이미지)에 정상적으로 액세스할 수 있도록 CORS 정책을 구성해야 할 수 있습니다.
- CSS 스타일과 마우스 오버 이벤트를 지원하려면 CSSStyleSheet 인터페이스를 통해 CSS 규칙에 액세스할 수 있어야 합니다.
기록 상태 확인¶
window.DATAFLUX_RUM.isRecording()을 호출하여 현재 페이지가 기록 중인지 확인하고, 세션 리플레이 탐색기에서 해당 Session에 리플레이 데이터가 생성되었는지 확인합니다. 프로덕션 환경에서는 비즈니스 요구 사항에 따라 sessionReplaySampleRate를 조정하세요.