Rumable SDK 소스 및 설정¶

이 페이지에서는 Rumable이 SDK를 주입, 로드, 초기화하는 방법을 설명합니다. 구성을 직접 작성하지 않아도 되는 방식은 원클릭 연동을 참조하세요. 수동 구성은 네 가지 연동 방식 전체 예시를 참조하세요. 최초 설치는 설치 및 연동을, 버전 업데이트와 롤백은 운영 안내를 참조하세요.

주입 방식 및 실행 순서¶

Rumable은 Web 서버가 반환하는 표준 <head> 뒤에 외부 스크립트를 추가하며, 비즈니스 소스 파일은 수정하지 않습니다. 소스와 로딩 방식은 서로 독립적입니다.

소스 및 방식	다운로드 위치	실행 순서
동일 도메인 + 비동기(기본값)	설치 패키지에 내장된 SDK를 웹사이트 동일 도메인에서 호스팅	초기화 스크립트를 비동기로 로드한 후 SDK를 동적으로 비동기 다운로드하고 완료 후 초기화
동일 도메인 + 동기	설치 패키지에 내장된 SDK를 웹사이트 동일 도메인에서 호스팅	SDK를 먼저 실행한 후 초기화 스크립트를 실행하고 이어서 페이지 파싱을 계속
CDN + 비동기	SDK는 공식 또는 자체 구축 CDN에서 가져오고 초기화 스크립트는 동일 도메인	초기화 스크립트가 CDN SDK를 비동기 다운로드하고 완료 후 초기화
CDN + 동기	SDK는 공식 또는 자체 구축 CDN에서 가져오고 초기화 스크립트는 동일 도메인	CDN SDK를 먼저 실행한 후 초기화 스크립트를 실행하고 이어서 페이지 파싱을 계속

동일 도메인 리소스는 웹사이트의 __rumable__/<站点ID>/ 아래에 있으며, 파일 이름에는 콘텐츠 다이제스트가 포함됩니다. 동일 도메인을 선택하면 SDK의 다운로드 위치만 변경되며, 데이터는 계속 설정된 전송 엔드포인트로 전송됩니다.

비동기 스크립트 다운로드는 HTML 파싱을 차단하지 않지만, 초기화 이전의 오류, 요청, 인터랙션은 수집되지 않을 수 있습니다. 동기 방식은 async, defer가 없는 일반 외부 스크립트 두 개를 사용하므로 이후 비즈니스 스크립트보다 먼저 초기화를 완료할 수 있습니다. 네트워크가 느리거나 CDN에 장애가 발생하면 이후 페이지 파싱과 첫 화면이 지연됩니다.

동기 방식은 SDK 로드 실패 또는 초기화 이전의 모든 이벤트를 캡처한다고 보장하지 않습니다. SDK 로드에 실패해도 동일 도메인 복사본으로 자동 전환되지 않으며, 동기 모드에서도 브라우저가 요청을 완료하거나 실패로 판정할 때까지 기다려야 합니다. 두 방식 모두 CSP를 자동으로 완화하지 않습니다.

source와 loading의 의미¶

source는 SDK를 어디서 다운로드하는지를 나타내고, loading은 SDK를 어떻게 로드하는지를 나타냅니다. 두 항목은 독립적으로 선택할 수 있습니다.

구성 항목	입력 값	의미
`source`	`"bundled"`	설치 패키지에 내장된 SDK를 사용하며 웹사이트 동일 도메인에서 제공
`source`	`"cdn"`	`url`로 지정한 CDN 주소에서 SDK 다운로드
`loading`	`"async"`	비동기: 페이지 파싱을 계속하고 SDK 로드 완료 후 수집 시작
`loading`	`"sync"`	동기: SDK를 먼저 로드하고 초기화한 후 이후 페이지 파싱을 계속
`url`	전체 HTTPS 스크립트 주소	CDN 사용 시에만 입력
`integrity`	`false` / `true`	브라우저 SRI 무결성 검증 활성화 여부. 기본값은 `false`이며, CDN에서 활성화하려면 아래 CORS 및 다이제스트 요구 사항을 충족해야 함

loading을 작성하지 않으면 비동기가 사용되며, loading = "async"를 명시적으로 작성해도 됩니다. 아래 예시는 모두 로딩 방식을 명시하여 바로 대조할 수 있도록 했습니다. [sites.sdk]는 TOML에서 이러한 옵션을 배치하는 구성 섹션 이름이며, 별도로 입력해야 하는 파라미터가 아닙니다.

설정 페이지에서 선택 및 원클릭 연동¶

먼저 원클릭 연동 절차를 사용하는 것이 좋습니다. 페이지에서 앱 파라미터를 입력하고 SDK 방식을 선택한 다음 생성된 명령을 복사하여 서버에서 실행합니다. 아래 TOML을 직접 작성할 필요가 없습니다. 설정 페이지의 'SDK 소스 및 로딩 방식 선택'에서 두 개의 드롭다운 상자를 제공합니다.

원하는 구성	'SDK 소스' 선택	'로딩 방식' 선택	CDN 주소
웹사이트 동일 도메인 + 비동기	웹사이트 동일 도메인(기본값)	비동기(기본값)	입력 안 함
웹사이트 동일 도메인 + 동기	웹사이트 동일 도메인(기본값)	동기	입력 안 함
CDN + 비동기	CDN	비동기(기본값)	SDK의 HTTPS 주소 입력
CDN + 동기	CDN	동기	SDK의 HTTPS 주소 입력

예를 들어 공식 CDN에서 동기 방식으로 로드하려면 'CDN'과 '동기'를 선택하고 CDN 주소에 https://static.guance.com/browser-sdk/v3/dataflux-rum.js를 입력합니다. 오른쪽 요약을 확인한 후 릴리스 버전을 읽고 TOML을 다운로드한 다음 페이지에서 생성된 명령을 실행합니다.

원클릭 연동은 위 네 가지 조합을 지원하며, 자동 발견으로 웹사이트를 찾을 때 CDN 및 동기 로딩을 선택하는 것도 지원합니다.

CLI가 이미 설치된 사이트¶

최초 연동은 latest 설정 페이지에서 생성한 명령을 그대로 사용합니다. 기존 사이트에서 SDK 소스나 로딩 방식을 수정해야 하는 경우 원래 구성, 사이트 ID, 상태 디렉터리를 유지한 채 구성 업데이트 및 업그레이드에 따라 다시 적용합니다. TOML을 다운로드하거나 설정 페이지를 새로고침해도 서버의 CLI와 SDK는 자동으로 업데이트되지 않습니다.

네 가지 연동 방식 전체 예시¶

아래 네 개의 코드 블록은 모두 Linux / Nginx의 전체 구성 파일입니다. 한 번에 하나만 선택하여 /etc/rumable/website.toml로 저장합니다. 네 개의 예시를 하나의 파일에 합치지 마세요. 기존 사이트는 원래 TOML을 먼저 백업하고, 원래 [sites.sdk] 섹션만 수정하며 기존 사이트 ID, 경로, 샘플링 등의 설정은 유지합니다.

최초 연동 시 다음 값을 교체합니다.

예시 값	교체 대상
`website`	이번 연동의 사이트 ID. 이후 업데이트 시에도 동일하게 유지
`https://www.example.com/`	웹사이트 주소. 경로는 `/`로 끝나야 함
`/usr/sbin/nginx`	실제 Nginx 실행 파일 경로
`YOUR_APPLICATION_ID`	Web 앱의 애플리케이션 ID
`https://openway.example.com`	콘솔에서 제공하는 OpenWay 주소. 프로토콜, 호스트, 선택적 포트만 입력
`YOUR_CLIENT_TOKEN`	해당 브라우저 접속 토큰

service, env, version은 비즈니스에 맞게 입력합니다. 여기서 version은 비즈니스 애플리케이션 버전이며 SDK 버전이 아닙니다. 예시는 전체 세션 샘플링을 활성화하고 리플레이를 비활성화한 상태이므로, 검증을 완료한 후 조정합니다.

예시 1: 웹사이트 동일 도메인 + 비동기¶

기본 방식입니다. SDK는 웹사이트 동일 도메인에서 제공하며, 페이지는 SDK 로드 완료를 기다리지 않습니다.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "bundled" # 웹사이트 동일 도메인
loading = "async" # 비동기 로드, SDK 다운로드 완료를 기다리지 않음

예시 2: 웹사이트 동일 도메인 + 동기¶

SDK는 웹사이트 동일 도메인에서 제공하며, 먼저 초기화한 후 페이지 파싱을 계속합니다.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "bundled" # 웹사이트 동일 도메인
loading = "sync" # SDK 로드 및 초기화 후 페이지 파싱 계속

예시 3: CDN + 비동기¶

브라우저가 지정한 CDN의 SDK를 비동기로 다운로드하며, 초기화 스크립트는 여전히 웹사이트 동일 도메인에서 제공합니다.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "cdn" # CDN에서 다운로드
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "async" # 비동기 로드, SDK 다운로드 완료를 기다리지 않음

예시 4: CDN + 동기¶

CDN SDK를 먼저 로드하고 초기화를 완료한 후 페이지 파싱을 계속합니다.

schemaVersion = 1

[[sites]]
id = "website"
publicURL = "https://www.example.com/"
includePaths = ["/"]
excludePaths = ["/downloads/"]
probePaths = ["/"]

[sites.nginx]
binary = "/usr/sbin/nginx"
attachmentReviewed = false

[sites.rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
service = "website"
env = "production"
version = "1.0.0"
sessionSampleRate = 100
sessionReplayEnabled = false
defaultPrivacyLevel = "mask"

[sites.sdk]
source = "cdn" # CDN에서 다운로드
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
integrity = false
loading = "sync" # SDK 로드 및 초기화 후 페이지 파싱 계속

IIS 및 DataKit에서 예시를 사용하는 방법¶

IIS는 동일한 [sites.sdk] 구성을 사용합니다. 선택한 예시의 전체 [sites.nginx] 섹션을 아래 섹션으로 교체하고 나머지 필드는 유지합니다.

[sites.iis]
site = "Default Web Site"
application = "/"
allowCompressionChanges = true

site는 실제 IIS 사이트 이름으로 변경합니다. allowCompressionChanges=true는 해당 애플리케이션의 IIS 정적 및 동적 압축을 끌 수 있도록 허용함을 의미하며, 비활성화하면 원래 설정을 복원합니다. 하위 애플리케이션 /shop은 publicURL=https://www.example.com/shop/에 해당하며, 주입 및 검증 경로에도 /shop/ 접두사를 사용해야 합니다.

DataKit으로 데이터를 전송하려면 [sites.rum]에서 site와 clientToken을 삭제하고 datakitOrigin = "https://datakit.example.com"으로 변경한 뒤 실제 주소로 교체합니다. 두 전송 방식은 상호 배타적이며 /v1/write/rum을 추가하지 않습니다.

저장 후 적용 방법¶

Nginx 최초 연동 시 버전이 일치하는 실제 CLI 경로로 다음을 실행합니다.

sudo rumable setup --config /etc/rumable/website.toml --state-dir /var/lib/rumable --site website

여기서 rumable은 설치된 CLI를 나타냅니다. PATH에 없으면 절대 경로로 교체하세요. 수정할 Nginx 연결을 확인한 후 적용하고, 브라우저 실행과 실제 데이터 적재를 확인합니다. 이미 연동된 사이트는 기존 상태 디렉터리를 유지하고, 구성을 수정한 후 enable을 다시 실행합니다.

Windows 최초 연동과 두 플랫폼에서의 검증은 설치 안내를, 이미 연동된 사이트의 구성 수정은 운영 안내를 참조하세요.

CDN 주소, 다이제스트 및 SRI¶

URL은 전체 HTTPS 스크립트 주소여야 하며, 계정/비밀번호, 쿼리 파라미터, 프래그먼트를 포함하지 않아야 합니다.
자체 구축 CDN은 선택한 설치 패키지와 완전히 동일한 SDK 바이트를 제공해야 합니다. 활성화 및 프로빙은 콘텐츠 다이제스트, JavaScript MIME, 일반 및 gzip 응답을 검사합니다.
브라우저 CSP에서 실제 CDN 주소를 허용해야 합니다. CDN을 선택해도 초기화 스크립트가 웹사이트 동일 도메인을 벗어나지 않습니다.
교차 출처 SRI를 사용하려면 CDN이 사이트 Origin 또는 *을 허용하는 Access-Control-Allow-Origin을 반환해야 합니다. 현재 공식 v3 주소는 기본적으로 SRI를 활성화하지 않습니다. 활성화 전에 실제 응답 헤더와 설치 검사를 기준으로 확인하세요.
공식 v3는 변경 가능한 주소이므로 프로빙 시 다이제스트 일치가 향후 콘텐츠를 고정하지 않습니다. 버전을 고정해야 한다면 동일 도메인 모드를 사용하거나 변경 불가능한 자체 구축 CDN 파일을 유지하세요.
bundled를 사용할 때는 url을 입력하거나 integrity를 활성화하지 마세요. 그렇지 않으면 검증이 거부됩니다.

자동 발견 구성¶

자동 발견은 도구가 서버에 이미 있는 웹사이트를 스캔한 후 연동 대상을 선택할 수 있게 해주는 기능으로, 웹사이트 주소와 Nginx/IIS 대상을 직접 입력하는 단계를 생략합니다. 이 방식은 server, [rum], [sdk]를 사용하며, [[sites]]를 포함하는 전체 구성과는 다른 형식입니다.

아래는 모두 완전한 자동 발견 구성입니다. 한 번에 하나만 선택하여 /etc/rumable/discovery.toml로 저장하고 애플리케이션 ID, OpenWay 주소, 토큰을 교체합니다. 이 구성은 setup --discover에만 전달할 수 있으며 enable에 직접 전달할 수 없습니다.

동일 도메인 비동기, 기본 동작을 사용하며 SDK 구성 섹션을 작성하지 않습니다.

schemaVersion = 1
server = "nginx"

[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false

CDN 동기, SDK 주소와 로딩 방식을 지정합니다.

schemaVersion = 1
server = "nginx"

[rum]
applicationId = "YOUR_APPLICATION_ID"
site = "https://openway.example.com"
clientToken = "YOUR_CLIENT_TOKEN"
sessionReplayEnabled = false

[sdk]
source = "cdn"
url = "https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
loading = "sync"
integrity = false

Windows에서는 server를 "iis"로 변경하고, 실제 권한에 따라 [rum] 앞에 최상위 allowCompressionChanges = true를 설정합니다. SDK 파라미터의 의미는 전체 구성과 동일하지만 구성 섹션 이름은 [sdk]이며 [sites.sdk]로 작성하면 안 됩니다.

Nginx는 실제 설치된 CLI로 실행하며, 터미널에서 사이트를 선택하면 연동 식별자가 출력됩니다.

sudo rumable setup --discover --config /etc/rumable/discovery.toml --state-dir /var/lib/rumable

Windows에서는 관리자 터미널에서 실제 exe, 구성 파일, 상태 디렉터리를 사용하여 setup --discover를 실행합니다. 이후에는 원래 사이트 ID, 대상, 상태 디렉터리를 계속 사용합니다. 동일 배포를 다른 임의 ID로 인계하지 마세요.

경로, 샘플링 및 리플레이¶

includePaths와 excludePaths는 대소문자를 구분하는 접두사 매칭을 사용하며 제외가 우선합니다. probePaths는 주입 범위 내에 있어야 하고 검증 가능한 HTML을 직접 반환해야 합니다. 경로는 서버가 해당 페이지를 재작성할지 여부를 결정하며, SDK의 Fetch/XHR 요청을 제외하는 것과 같지 않고 SPA가 라우트를 전환할 때 주입 여부를 다시 판단하지도 않습니다.

리플레이는 기본적으로 비활성화되어 있습니다. 전체 구성에 이미 있는 [sites.rum]에서 다음 필드를 조정합니다. 해당 테이블을 중복으로 추가하지 마세요.

sessionSampleRate = 100
sessionReplayEnabled = true
sessionReplaySampleRate = 20
sessionReplayOnErrorSampleRate = 0
defaultPrivacyLevel = "mask"

리플레이는 RUM 세션 샘플링에 의존하므로 샘플링 비율을 변경한 후 새 세션으로 검증합니다. 리플레이, 요청 압축, 원격 구성에는 Worker가 필요할 수 있습니다. 기본 Blob Worker는 CSP에서 blob:을 허용해야 하며, 외부 Worker는 사용자 동일 도메인에서 호스팅하고 버전 일치를 유지해야 합니다.

자세한 샘플링 의미는 샘플링 구성을 참조하세요. setUser, 수동 startView, 사용자 정의 이벤트 및 함수 콜백은 여전히 비즈니스 코드가 필요합니다. Rumable의 정적 구성은 이러한 호출을 자동으로 대체할 수 없습니다. '애플리케이션 버전'은 비즈니스 레이블이며, 'SDK 원격 구성'은 수집 파라미터를 조정합니다. 둘 다 SDK 파일을 업그레이드하지 않습니다.

설정 페이지 또는 CLI가 선택한 방식을 지원하지 않는 경우¶

latest 설정 페이지를 열고 릴리스 버전을 다시 읽은 후 설치 명령을 생성합니다. 설치된 CLI가 loading 또는 [sdk]를 인식하지 못한다는 메시지를 표시하면 업그레이드 절차에 따라 CLI를 업데이트한 후 기존 사이트 구성을 다시 적용합니다. 업그레이드 시 기존 사이트 ID, 대상, 상태 디렉터리를 유지합니다.