Rumable 업그레이드, 롤백 및 문제 해결¶

이 페이지는 이미 연동된 사이트를 위한 문서입니다. 작업 전에 원래 구성, 사이트 ID, CLI 경로, 상태 디렉터리, 웹 서버 구성 백업을 보존하세요. 최초 연동은 설치 안내를, SDK 선택은 구성 안내를 참조하세요.

원래 배포 정보 준비¶

아래 명령은 모두 원래 배포의 CLI, 상태 디렉터리, 사이트 ID를 사용합니다. 터미널을 다시 열면 먼저 변수를 설정하세요. 사용자 정의 상태 디렉터리를 사용한 경우 기본값을 원래 값으로 변경하세요. 각 단계가 성공한 후 계속 진행하고, 오류가 발생하면 먼저 터미널 안내에 따라 처리하세요.

Linux(sudo 권한 필요):

rumable="/원래 배포의 실제 설치 디렉터리로 교체/rumable"
state="/var/lib/rumable"
site_id="원래 사이트 ID로 교체"

Windows(관리자 터미널):

$rumable = Read-Host '원래 배포에서 사용한 rumable.exe 전체 경로 입력'
$state = Join-Path $env:ProgramData 'Rumable'
$siteId = Read-Host '원래 사이트 ID 입력'

연동된 사이트 수정¶

먼저 원래 TOML, 전체 상태 디렉터리, 서버 구성을 백업한 다음 저장된 TOML 형식에 따라 절차를 선택하세요.

자동 검색 구성¶

보존된 TOML을 기준으로 구성 페이지로 돌아가 전체 파라미터를 입력하고, 수정이 필요한 옵션만 조정하며 원래 샘플링, 리플레이, SDK 설정을 유지하세요. 선택한 설치 패키지를 읽고 확인한 후 새 TOML을 저장하고 원래 서버에서 생성된 명령을 실행한 다음 원래 사이트와 바인딩을 선택하세요. 원클릭 명령을 다시 실행해도 선택한 패키지가 설치되므로 SDK 버전도 함께 확인해야 합니다.

원래 배포가 사용자 정의 상태 디렉터리를 사용하거나 현재 CLI로 수정된 검색 구성을 적용하려면 다음 명령을 실행하고, 구성 경로는 저장된 실제 파일로 교체하세요.

Linux:

sudo "$rumable" setup --discover --config /etc/rumable/discovery.toml --state-dir "$state"

Windows:

& $rumable setup --discover --config 'C:\ProgramData\RumableConfig\discovery.toml' --state-dir $state
if ($LASTEXITCODE -ne 0) { throw '구성 적용 실패, 먼저 원인을 확인하세요' }

동일한 대상 검색은 원래 ID, URL, 경로 범위를 재사용합니다. 출력된 사이트 ID가 원래 기록과 일치하는지 확인하고, 새 수동 ID로 기존 배포를 인수하지 마세요. 검색 구성은 enable에 직접 전달할 수 없습니다.

전체 사이트 구성¶

원본 TOML을 편집하고 원래 사이트 ID와 배포 대상을 유지한 다음 enable을 실행하세요. init/render를 반복하지 말고 상태 디렉터리를 삭제하지 마세요. 아래 구성 경로는 원본 파일로 교체하세요.

Linux:

config="/etc/rumable/website.toml"
sudo "$rumable" enable --config "$config" --state-dir "$state" --site "$site_id"

Windows:

$config = 'C:\ProgramData\RumableConfig\website.toml'
& $rumable enable --config $config --state-dir $state --site $siteId
if ($LASTEXITCODE -ne 0) { throw '구성 적용 실패, 먼저 원인을 확인하세요' }

두 방식 모두 완료한 후에는 연동 결과 확인에 따라 status/probe를 실행하고 새 페이지와 실제 데이터를 확인하세요. SDK 출처, 로드 방식, RUM 파라미터가 모두 이 절차로 업데이트됩니다.

자동 사이트의 경로 범위나 probePaths를 조정할 때는 원래 ID, URL, 서버 대상을 기준으로 전체 구성을 정리하고 사이트 신원을 확인한 후 enable을 실행하세요. publicURL, Nginx 프로그램/시작 파라미터 또는 IIS 사이트/애플리케이션 변경은 배포 대상 마이그레이션에 해당하므로 일반 구성 업데이트로는 완료할 수 없습니다.

SDK 업데이트 방법¶

동일 도메인 SDK는 설치 패키지에 고정되어 있으므로 백그라운드에서 자동으로 업데이트되지 않습니다. 릴리스 관리자가 SDK를 동기화하고 검증한 후 새 패키지를 게시합니다. 웹사이트 관리자가 직접 업그레이드하여 적용해야 합니다. CLI만 교체하거나 latest를 읽거나 비즈니스 version을 수정하거나 remoteConfiguration을 활성화하는 것만으로는 배포된 동일 도메인 SDK가 업데이트되지 않습니다.

업그레이드 단계:

1. 원래 TOML, 전체 상태 디렉터리, 서버 구성을 백업하고 이전 CLI를 보존하세요.
2. 릴리스 매니페스트에서 새 패키지를 선택하고 다이제스트를 검증한 후 새 디렉터리에 설치하세요. rumable version과 패키지 내 버전 정보를 확인하세요.
3. rumable / $rumable을 새 CLI로 지정하고 원래 사이트 ID와 상태 디렉터리를 유지하세요. 구성 유형에 따라 enable 또는 setup --discover를 실행하세요.
4. IIS가 이전 배포를 처음 인수하면 풀 소유권을 기록하고 한 번 재활용합니다. 이후 구성이 완전히 동일한 반복 작업은 추가로 재활용하지 않습니다. 먼저 원래 브라우저 페이지에서 캐시를 유지한 채 일반 새로고침으로 현재 초기화 스크립트를 받았는지 확인한 후 status/probe를 실행하세요.
5. CDN, 프록시 또는 Service Worker가 여전히 이전 HTML을 반환하면 응답 증거를 저장한 후 해당 캐시 정책에 따라 처리하세요. 그런 다음 새 페이지, 새 세션, SDK 다운로드, 기존 비즈니스, 실제 RUM 데이터 적재, 리플레이를 확인하세요.

공식 가변 CDN이 먼저 업데이트된 경우 이전 CLI의 check/enable/probe는 다이제스트 불일치로 실패할 수 있습니다. 이 경우 일치하는 SDK가 포함된 새 패키지를 사용하거나 현재 패키지와 일치하는 고정 CDN 파일로 전환하세요. 불일치를 우회하려고 다이제스트 검사를 끄지 마세요. 이미 열린 페이지는 SDK를 핫 리플레이스하지 않으며, 외부 Worker도 버전을 일치시켜야 합니다.

IIS 애플리케이션 풀 및 구성 적용¶

대상 애플리케이션은 시작된 전용 애플리케이션 풀을 사용해야 하며, 하위 애플리케이션도 자체 풀이 있어야 합니다. 활성화, 업데이트, 비활성화, 기록 롤백, 장애 복구는 먼저 구성을 기록하고 복구 상태를 저장한 다음 대상 풀을 재활용하고 이전 작업자 프로세스가 종료될 때까지 대기한 후 마지막으로 HTTP를 확인합니다. 완전히 동일한 반복 설치 또는 비활성화는 추가로 재활용하지 않습니다.

재활용하면 프로세스 내 세션이 유실될 수 있으므로 적절한 유지보수 시간을 계획하세요. 이 도구는 애플리케이션 풀을 자동으로 할당하지 않으며, 공유 풀을 재활용하지 않고, IIS 전체를 재시작하지 않습니다. 연동 후 관리 풀 이름을 직접 변경하거나 다른 애플리케이션을 추가하지 마세요. 조정이 필요하면 먼저 원래 배포 정보로 비활성화한 후 마이그레이션을 계획하여 소유권 드리프트 보호가 트리거되지 않도록 하세요.

IIS 연동은 선택한 애플리케이션의 정적 및 동적 압축을 해제하며, 비활성화 시 원래 로컬 설정 또는 상속 관계를 복원합니다. 파일 수준 압축 재정의, 백엔드 압축 또는 외부 HTML 캐시는 여전히 페이지에 영향을 줄 수 있습니다. 활성화 시 대상 IIS에 도달하는 관리형 HTML 탐색 요청은 이전 조건부 검증 헤더를 지워 이전 본문이 재사용되지 않도록 합니다. 제외 경로와 공용 SDK 리소스는 이 처리를 사용하지 않습니다.

이전 worker가 오래도록 종료되지 않으면 작업이 실패하고 복구를 시도할 수 있습니다. 복구가 불완전하면 트랜잭션을 보존하세요. 먼저 긴 요청과 대상 풀 상태를 확인하고, 전체 출력과 상태 백업을 보존한 후, 복구가 가능해지면 원래 사이트 ID와 상태 디렉터리로 rollback을 실행하세요. 검사를 우회하려고 트랜잭션을 삭제하거나 상태를 수동으로 편집하거나 비즈니스 프로세스를 강제 종료하지 마세요.

작업 프로브 실패는 사이트 전용 상태 디렉터리의 last-operation-probe-failure.json에 기록되고, 복구 프로브 실패는 last-recovery-probe-failure.json에 별도로 저장됩니다. 재시도 전에 이 파일들을 저장하고 타임스탬프 기준으로 이번 작업과 대조하세요. 자동 복구가 성공한 후에도 이전 실패 기록은 남아 있으므로 파일이 존재한다고 해서 현재도 실패 중인 것은 아닙니다. 지원 담당자에게는 비식별화된 사본을 제공하고, 전체 상태 백업이나 토큰은 공개하지 마세요.

비활성화, 롤백 및 제거¶

수집 비활성화¶

먼저 이 페이지 상단의 변수를 설정하세요. 수집만 중지하려면 비활성화와 확인을 실행하면 됩니다.

Linux:

sudo "$rumable" disable --state-dir "$state" --site "$site_id"
sudo "$rumable" probe --state-dir "$state" --site "$site_id"

Windows:

& $rumable disable --state-dir $state --site $siteId
if ($LASTEXITCODE -ne 0) { throw '비활성화 실패, 먼저 원인을 확인하세요' }
& $rumable probe --state-dir $state --site $siteId

비활성화는 새 HTML 주입만 중지하며 이전 페이지가 사용할 리소스는 보존합니다. 기존 페이지와 이전 HTML 캐시에서 SDK가 계속 실행될 수 있습니다. Nginx 자동 연결 시 적용된 압축, 캐시 또는 요청 헤더 조정도 계속 유지될 수 있습니다.

IIS 비활성화는 원래 압축 설정과 상속 관계를 복원하고 대상 풀을 재활용합니다. 일반 새로고침 후 새로 로드된 HTML에는 이 배포의 주입이 포함되지 않아야 합니다. 비즈니스 캐시 정책이 복원된 후 304가 반환될 수 있으므로 실제로 재사용되는 본문에 주입이 남아 있는지 확인하세요. 이전 해시 스크립트와 공용 리소스 매핑은 이전 페이지가 사용할 수 있도록 보존됩니다.

이전 배포 복원¶

롤백은 별도의 작업이며 수집을 다시 활성화할 수 있습니다. 이전 성공 배포를 복원해야 할 때만 실행하고, 정상 비활성화 후 연속으로 실행하지 마세요.

Linux:

sudo "$rumable" rollback --state-dir "$state" --site "$site_id"

Windows:

& $rumable rollback --state-dir $state --site $siteId

중단된 트랜잭션이 있으면 rollback은 먼저 트랜잭션 복구를 시도하고, 그렇지 않으면 현재 스냅샷과 이전 성공 스냅샷 사이를 전환합니다. 무제한 기록 롤백이 아니며 디스크의 TOML을 자동으로 복원하지 않습니다. 롤백 후 다시 enable을 실행하면 현재 TOML이 다시 적용되므로 원하는 구성을 함께 확인한 후 상태, 페이지, 데이터를 점검하세요.

완전 제거¶

먼저 비활성화하고 이전 HTML 캐시를 정리한 다음 제거 범위를 미리 봅니다.

Linux:

sudo "$rumable" uninstall --state-dir "$state" --site "$site_id" --dry-run

Windows:

& $rumable uninstall --state-dir $state --site $siteId --dry-run

미리 보기 결과를 확인하고 대상과 변경 범위를 확인한 후 제거를 실행하세요.

Linux:

sudo "$rumable" uninstall --state-dir "$state" --site "$site_id"

Windows:

& $rumable uninstall --state-dir $state --site $siteId

uninstall은 관리 설정을 복원하고 리소스 매핑을 제거하며 상태를 보관합니다. 이후 일반 rollback으로 해당 사이트를 직접 복원할 수 없습니다. CLI나 사용자가 직접 설치한 웹 서버는 자동으로 삭제하지 않습니다.

Linux Nginx 최초 자동 연결만 되돌릴 경우 먼저 disable을 실행한 다음 rollback --attachment --dry-run으로 미리 보고, 확인 후 rollback --attachment를 실행하세요. 외부 수정이나 나중에 같은 파일에 연결된 다른 사이트가 복원을 막을 수 있으므로 차이를 검토하세요. 백업이나 상태 파일을 삭제하면서 강행하지 마세요.

수동으로 추가한 Nginx include에는 자동 연결 백업이 없으므로 rollback --attachment로 되돌릴 수 있다고 보장할 수 없습니다. 설치 패키지 가이드에 따라 이번 수동 include를 제거하고 관련 지시문을 복원한 후, 구성 검사와 리로드가 성공하면 관리 상태를 보관하세요. 서버가 계속 참조하는 디렉터리를 직접 삭제하지 마세요.

자주 묻는 질문¶

Rumable의 기본 자동 연동은 브라우저 RUM을 처리하며, 서버 측 OTel은 별도의 기능입니다. Web SDK 연동을 위해 서버 측 Trace 구성 요소를 부수적으로 설치하거나 수정하지 마세요.