Rumable로 Web RUM 원클릭 연동¶
Rumable은 Nginx 또는 IIS를 통해 웹사이트가 반환하는 HTML에 Web RUM 스크립트를 삽입합니다. 웹 서버를 관리할 수 있고 프런트엔드 소스 코드 수정을 피하려는 웹사이트에 적합합니다. SDK는 방문자 브라우저에서 실행되며, 데이터를 Guance의 OpenWay 또는 사용자가 구성한 DataKit에 직접 전송합니다. CLI는 연동 완료 후 종료되며 상주형 수집 서비스가 아닙니다.
최초 연동에는 원클릭 연동을 권장합니다. 설정을 직접 작성할 필요가 없습니다. 오프라인이거나 단계별 검토를 원하는 환경에서는 단계별 설치를 사용하세요. SDK 출처, 로드 방식, 전체 TOML 예시는 설정 설명을 참조하고, 이미 연동된 사이트의 업데이트와 복구는 운영 설명을 참조하세요. 설치 및 일상적인 사용에는 Git, Go, Node.js, 데이터베이스가 필요하지 않습니다.
원클릭 연동(권장)¶
구성 페이지 열기 → 앱 매개변수 입력 → 설치 명령 복사 → 웹 서버에서 실행 → 사이트 선택 → 데이터 검수. TOML을 직접 작성할 필요도 없고 CLI를 미리 설치할 필요도 없습니다. 명령이 해당 플랫폼의 CLI를 다운로드하고 검증한 뒤 설치한 다음 사이트를 연동합니다. 서버는 다운로드 주소에 접근할 수 있어야 하며 아래 서버 조건을 충족해야 합니다.
1단계: 페이지에서 매개변수 입력¶
먼저 'RUM > 앱 목록'에서 Web 앱을 생성하여 앱 ID와 전송 매개변수를 확인하고 서버 조건을 확인합니다.
원클릭 연동 구성 페이지를 열고 앱 매개변수를 입력한 뒤 플랫폼을 선택합니다. 먼저 기본 동일 출처 비동기 방식으로 검증을 진행합니다. 최초 검증 시 세션 샘플링 100%, 리플레이 비활성화를 권장합니다.
예를 들어 'Linux / Nginx + 웹사이트 동일 출처 + 비동기' 구성을 페이지에 입력합니다.
| 페이지 옵션 | 예시 | 사용자가 할 일 |
|---|---|---|
| 전송 방식 | OpenWay | DataKit을 선택하고 해당 주소를 입력할 수도 있습니다 |
| 앱 ID | YOUR_APPLICATION_ID |
콘솔의 Web 앱 ID로 바꿔주세요 |
| 전송 주소 | https://openway.example.com |
실제 OpenWay 주소로 바꾸세요. API 경로를 추가하지 마세요 |
| Client Token | YOUR_CLIENT_TOKEN |
해당 브라우저 클라이언트 토큰으로 바꾸세요 |
| SDK 출처 | 웹사이트 동일 출처(기본값) | 최초 검증 시 기본값을 유지할 수 있습니다 |
| 로드 방식 | 비동기(기본값) | 최초 검증 시 기본값을 유지할 수 있습니다 |
| 서버 유형 | Linux · Nginx | Windows 사이트는 IIS · Windows를 선택하세요 |
| 사이트와 경로 수동 지정 | 선택 안 함 | 명령 실행 시 사이트를 자동으로 검색하고 선택합니다 |
동일한 프로세스로 동일 출처/CDN과 동기/비동기의 네 가지 조합을 지원하며 TOML을 직접 작성할 필요가 없습니다. CDN을 선택하면 SDK의 HTTPS 스크립트 주소를 입력합니다. SDK를 먼저 초기화한 후 이후 비즈니스 스크립트를 실행해야 하는 경우 '동기'를 선택합니다. 구체적인 차이는 SDK 출처 및 로드 방식을 참조하세요.
2단계: 릴리스 버전 확인 및 명령 복사¶
- '릴리스 버전 읽기'를 클릭하여 페이지에 Rumable 및 Web SDK 버전이 표시되는지 확인합니다.
- TOML을 다운로드하여 보관합니다. 이후 수정과 복구에 사용합니다. 수동 편집은 필요하지 않습니다.
- '설치 명령' 탭으로 전환하여 페이지에서 생성된 전체 명령을 복사합니다. 명령만 복사하는 것은 서버를 변경하지 않으며, 실행한 후에 연동이 시작됩니다.
명령에는 사용자가 입력한 구성이 포함되어 있으므로 다른 사람의 명령을 사용할 수 없습니다. 아래는 자동 검색 연동의 원클릭 명령 구조만 보여 줍니다. 설치 프로그램 주소, 릴리스 디렉터리, 인코딩 구성은 모두 페이지에서 채워집니다. 플레이스홀더 예시를 직접 실행하지 마세요. 실제 실행 시 페이지에서 생성된 전체 명령을 복사하고 버전 번호를 수동으로 바꿀 필요가 없습니다.
3단계: 서버에서 원클릭 명령 실행¶
Linux / Nginx: Nginx를 실행 중인 서버에 로그인하여 sudo 권한이 있는 터미널에서 페이지가 생성한 Bash 명령을 붙여넣습니다. 명령 형식은 다음과 같습니다.
bash -o pipefail -c 'curl --proto "=https" --proto-redir "=https" -fsSL "INSTALLER_URL_FROM_PAGE" | sudo sh -s -- --base-url "ARTIFACT_BASE_FROM_PAGE" --config "CONFIG_FROM_PAGE" --discover'
Windows / IIS: 관리자 권한으로 Windows PowerShell 5.1+를 열고 페이지가 생성한 PowerShell 명령을 붙여넣습니다. cmd.exe에서는 실행하지 마세요. 명령 형식은 다음과 같습니다.
실행 전에 대상 앱이 시작된 전용 애플리케이션 풀을 사용하는지 확인하고, 하위 앱에도 별도의 풀이 할당되어 있어야 합니다. 연동 시 대상 풀이 재활용되고 이전 작업자 프로세스가 종료될 때까지 대기하므로 프로세스 내 세션이 유실될 수 있습니다. 재활용 영향을 수용할 수 있는 유지보수 시간대에 작업하세요.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'INSTALLER_URL_FROM_PAGE').Content)) -BaseUrl 'ARTIFACT_BASE_FROM_PAGE' -Config 'CONFIG_FROM_PAGE' -Discover
설치 프로그램은 시스템과 CPU에 해당하는 설치 패키지를 자동으로 선택하고 압축 패키지의 체크섬을 검증한 뒤 CLI를 설치하고 구성을 읽어 사이트를 검색합니다. 후보가 하나뿐이면 자동으로 선택합니다. 사이트나 바인딩이 여러 개인 경우 터미널 안내에 따라 대상을 선택하고, 필요 시 접근 URL을 보완하거나 압축 조정을 확인합니다. 원클릭 설치 프로그램에는 연동 확인 절차가 포함되므로 명령을 실행하면 앱 변경에 동의하는 것입니다. 대상을 선택하고 필요한 안내를 완료하면 도구가 직접 주입과 HTTP 검증을 수행합니다.
원클릭 연동에서도 모호한 경우 사이트를 선택해야 합니다. 첫 번째 사이트를 기본적으로 수정하지 않으며 Nginx, IIS 또는 URL Rewrite를 자동으로 설치하지 않습니다. 대상을 직접 지정해야 한다면 페이지에서 '사이트와 경로 수동 지정'을 선택한 후 원클릭 명령을 계속 생성할 수 있습니다. 복잡한 구성이나 오프라인 서버에서는 단계별 설치를 사용하세요.
4단계: 결과 저장 및 검수¶
터미널에 RUM setup complete가 표시되면 출력된 사이트 ID와 URL을 기록합니다. 고급 수동 모드에서는 구성의 id와 publicURL을 기준으로 합니다. 선택한 버전, 다운로드한 TOML, 아래 표에 따라 확인된 CLI 경로 및 상태 디렉터리를 저장합니다. 상태 디렉터리를 전체 백업하고, Nginx가 Backup:을 출력하면 해당 경로를 별도로 기록합니다. 그런 다음 연동 결과 확인에 따라 브라우저 수집과 실제 데이터 적재를 확인합니다. 검수가 통과되면 최초 연동이 완료된 것이므로 단계별 설치를 다시 실행할 필요가 없습니다.
구성은 로컬 브라우저에서 생성되며 앱 구성을 다운로드 사이트로 제출하지 않습니다. 명령의 Base64는 인코딩일 뿐 암호화가 아닙니다. Client Token이 포함된 전체 명령을 공개하지 마세요. 원클릭 설치 프로그램은 임시 TOML을 정리하므로 페이지에서 다운로드한 구성은 보관해야 합니다.
기본 설치 위치:
| 플랫폼 | CLI | 관리 상태 |
|---|---|---|
| Linux | /opt/rumable/<版本>/rumable |
/var/lib/rumable |
| Windows | Program Files 기본 경로의 Rumable\<版本>\rumable.exe |
%ProgramData%\Rumable |
표의 버전은 구성 페이지에 표시된 이번 선택 버전을 의미합니다. 원클릭 설치는 CLI를 PATH에 자동으로 추가하지 않습니다. 상태 디렉터리는 배포, 복구, 귀속 정보를 저장하므로 보관하고 백업해야 합니다. 이후 작업에서는 기존 사이트 ID와 상태 디렉터리를 계속 사용하고, 기존 구성 유형에 따라 업데이트 방식을 선택합니다.
고정 진입점 및 설치 패키지 선택¶
- 온라인 구성 페이지: 구성을 입력하고 설치 명령을 생성합니다.
- 릴리스 매니페스트: 권장 설치 패키지, 내장 SDK, 다운로드 파일 및 검증 정보를 읽어옵니다.
구성 페이지는 매니페스트를 한 번 읽은 후 명령이 해당 릴리스의 설치 프로그램과 설치 패키지를 가리키도록 하고, 함께 제공되는 체크섬으로 검증합니다. 문서 진입점은 항상 latest를 사용합니다. 구체적인 버전, 패키지 이름, 검증 정보는 릴리스 프로세스에서 업데이트되므로 사용자가 문서에서 버전 번호를 바꿀 필요가 없습니다.
latest를 읽는 것은 이번에 어떤 설치 패키지를 사용할지 결정할 뿐이며, 이미 연동된 사이트를 자동으로 업그레이드하지 않습니다. 이미 연동된 사이트는 설치 시 기록된 CLI 경로와 상태 디렉터리를 계속 사용합니다. 업그레이드 시 업그레이드 절차에 따라 새 패키지를 직접 선택하고 적용합니다.
연동 전 준비 및 서버 조건¶
- 'RUM > 앱 목록'에서 Web 앱을 새로 만들고
applicationId를 확인합니다. - 전송 방식을 선택합니다. OpenWay는
site와 브라우저clientToken을 사용하고, DataKit 직접 연결은datakitOrigin을 사용합니다. 자세한 내용은 Web 앱 연동을 참조하세요. 관리 API Key는 사용하지 마세요. - 동일한 SDK가 사이트에 중복 연동되지 않았는지 확인합니다. 비즈니스 코드에 번들된 연동도 수동으로 확인해야 합니다.
- HTTP 200 HTML을 직접 반환하는 검수용 주소를 준비합니다. 페이지에는 표준
<head>시작 태그가 필요하며, 리디렉션 페이지, 로그인 페이지 또는 다운로드 주소로 대체하지 마세요. - 웹 서버 구성을 백업하고 작업 권한과 유지보수 시간대를 확인합니다. 적용 시 Nginx 구성을 검사하고 리로드하거나, 대상 IIS 앱의 관리 규칙을 수정하고 해당 전용 애플리케이션 풀을 재활용합니다.
브라우저는 전송 주소에 접근할 수 있어야 합니다. HTTPS 웹사이트에서는 HTTPS 전송 엔드포인트를 사용합니다. CSP는 동일 출처 초기화 스크립트, 실제 SDK 주소, 전송 대상, 필요한 Worker를 허용해야 합니다. Rumable은 CSP를 자동으로 완화하지 않으며 인라인 JavaScript도 주입하지 않습니다.
Linux / Nginx 조건¶
- Nginx 최소 기술 버전은 1.9.4이며
http_sub_module이 포함되어야 합니다. 유지보수되는 버전을 우선 선택하세요. - Linux x86, x64, ARM64 패키지가 제공됩니다. 원클릭 설치는 최신 패키지를 선택하며, 구형 시스템에서는 일치하는 legacy 패키지를 사용합니다.
- root 또는 sudo를 사용합니다. 원클릭 명령에는 Bash, curl, CA 인증서 및 일반적인 압축 해제·검증 도구가 필요합니다.
- 교체 단계로 들어가는 HTML은 압축되지 않은 상태여야 합니다. 자동 적용은 대상 처리 위치의 소스 압축, 조건부 요청, 캐시를 조정하므로 실제 영향을 검토해야 합니다. 출력 gzip은 유지할 수 있습니다.
- Nginx 자동 검색, 자동 적용, 적용 롤백은 현재 Linux에서만 지원됩니다.
Windows / IIS 조건¶
- IIS 7.5+, URL Rewrite 2.x, Static Content 및 익명 정적 파일 액세스가 준비되어 있어야 합니다. 도구는 이러한 구성 요소를 자동으로 설치하지 않습니다.
- 원클릭 설치에는 관리자 권한과 Windows PowerShell 5.1+가 필요합니다. CLI의 IIS 관리 브리지에는 시스템 네이티브 64비트 PowerShell 3.0+가 필요합니다.
- Windows 10 / Server 2016+에서는 최신 패키지를 사용하고, 구형 Windows에서는 해당 legacy 패키지를 사용합니다. 실제 32비트 Windows에서는 IIS를 관리할 수 없습니다.
- 대상 애플리케이션 풀이 시작되어 있어야 하며 해당 앱만 서비스해야 합니다. 부모 앱과 하위 앱은 각각 자체 풀을 사용합니다. IIS 관리자의 '애플리케이션 풀 > 애플리케이션 보기'에서 소속을 확인하세요. 공유 풀은 먼저 운영 담당자가 조정해야 하며, 도구는 풀을 자동으로 할당하거나 시작하지 않고, 공유 풀을 재활용하지 않으며, IIS 전체를 재시작하지 않습니다.
- 앱의
/__rumable__/리소스는 비즈니스 라우팅, 인바운드 재작성 또는 앱 핸들러가 가로챌 수 없어야 하며, JavaScript MIME 유형이 유효해야 합니다. - 대상 앱의 IIS 정적 및 동적 압축을 끌 수 있어야 하며, 비활성화 시 원래 설정으로 복원합니다. 이는 해당 앱 내 다른 응답의 압축에도 영향을 줍니다. 동적 앱이나 역방향 프록시의 백엔드도 압축되지 않은 HTML을 반환해야 합니다.
방문자 브라우저는 Web SDK 호환성 요구 사항을 충족해야 합니다.
오프라인 또는 단계별 설치¶
인터넷에 연결된 머신에서 릴리스 매니페스트에서 운영체제, CPU, modern/legacy 유형과 일치하는 압축 패키지를 선택하고 같은 버전의 SHA256SUMS도 함께 받습니다. 파일 이름에 해당하는 SHA-256을 검증한 후 압축을 해제합니다. 오프라인 서버는 원본 압축 패키지와 체크섬 목록을 받은 후 다시 검증합니다. 전체 압축 패키지에는 CLI, 예시, 사용 가이드, 버전 정보가 포함됩니다.
설치 후 먼저 rumable version을 실행합니다. UTF-8 TOML을 만들고 전체 사이트 구성을 참조하여 실제 값을 입력한 뒤 setup을 실행합니다. 아래 경로와 사이트 ID는 예시일 뿐입니다. 기존 구성 파일을 덮어쓰지 마세요.
rumable="/请替换为实际安装目录/rumable"
sudo "$rumable" setup \
--config /etc/rumable/website.toml \
--state-dir /var/lib/rumable --site website
Windows에서는 관리자 터미널을 사용하고, 경로를 실제 설치 위치로 바꿉니다.
$rumable = Read-Host '输入实际安装的 rumable.exe 完整路径'
& $rumable setup `
--config 'C:\Rumable\website.toml' `
--state-dir "$env:ProgramData\Rumable" --site website
if ($LASTEXITCODE -ne 0) { throw 'Rumable 接入失败，请按终端输出检查' }
setup은 연동을 준비하고 적용합니다. Nginx는 수정할 적용 내역을 표시하며, 확인 후 쓰기, 검사, 리로드를 진행합니다. 복잡하거나 지원되지 않는 처리 구성은 설치 패키지 가이드의 수동 적용 절차를 사용해야 합니다. Nginx 적용 내역만 미리 보려면 가이드에 따라 먼저 render한 다음 attach --dry-run을 실행합니다.
연동 결과 확인¶
IIS 연동 후에는 먼저 기존 브라우저 페이지에서 캐시를 유지한 채 일반 새로고침을 한 번 실행합니다. 강력 새로고침이나 Disable cache는 사용하지 마세요. 홈페이지와 그 외 주요 HTML 페이지를 확인합니다. 200을 반환하고 현재 초기화 스크립트가 하나 포함되어야 하며 비즈니스 콘텐츠가 정상이어야 합니다. 자동 검색은 기본적으로 보통 홈페이지만 확인하므로, 다른 템플릿까지 확인해야 하면 해당 probePaths를 구성합니다. 이상이 있으면 먼저 요청, 응답, 실패 출력을 저장한 다음 운영 설명에 따라 문제를 해결합니다.
실제 CLI 경로, 상태 디렉터리, 터미널에 기록된 사이트 ID를 사용하여 실행합니다. 아래 경로와 ID는 반드시 원래 배포 값으로 바꿔야 합니다.
Linux(sudo 권한 필요):
rumable="/请替换为实际安装目录/rumable"
state="/var/lib/rumable"
site_id="替换为原站点ID"
sudo "$rumable" status --state-dir "$state" --site "$site_id"
sudo "$rumable" probe --state-dir "$state" --site "$site_id"
Windows(관리자 터미널):
$rumable = Read-Host '输入实际安装的 rumable.exe 完整路径'
$state = Join-Path $env:ProgramData 'Rumable'
$siteId = Read-Host '输入原站点 ID'
& $rumable status --state-dir $state --site $siteId
& $rumable probe --state-dir $state --site $siteId
검수는 다음 단계로 확인합니다.
| 단계 | 확인 내용 |
|---|---|
| 관리 상태 | rumEnabled=true, drift="", pendingTransaction=false |
| HTML 및 리소스 | probe 성공, 페이지에 예상되는 스크립트 포함, 초기화 스크립트와 SDK가 올바른 JavaScript 콘텐츠 반환 |
| 브라우저 실행 | 개발자 도구에 예상치 못한 초기화 오류가 없고 기존 비즈니스가 정상; 동기 모드에서는 이후 비즈니스 스크립트 전에 초기화 |
| 데이터 전송 | 네트워크 탭에 /v1/write/rum 요청이 나타나고 응답이 정상 |
| 실제 데이터 적재 | 앱의 탐색기에서 이번 페이지, 작업 또는 오류 이벤트 확인; 리플레이를 켠 후 실제 세션을 재생할 수 있는지 확인 |
probe는 HTTP 주입과 리소스 접근 가능 여부를 검증하며 브라우저 SDK를 실행하지 않습니다. 수신 측을 시뮬레이션해 성공이 반환되어도 실제 데이터 적재 확인을 대체할 수 없습니다. 전체 검수가 완료된 후 샘플링과 리플레이를 조정하세요.