Rumable Upgrade, Rollback, and Troubleshooting¶

This page is for sites that have already been onboarded. Before operating, keep backups of the original configuration, site ID, CLI path, state directory, and web server configuration. For first-time onboarding, see Installation Instructions; for SDK selection, see Configuration Instructions.

Prepare the Original Deployment Information¶

All of the following commands use the CLI, state directory, and site ID of the original deployment. When you reopen a terminal, set the variables first; if you used a custom state directory, change the default values to the original ones. Continue only after each step succeeds; if an error occurs, first handle it according to the terminal prompt.

Linux (with sudo privileges):

rumable="/replace/with/the/actual/installation/directory/of/the/original/deployment/rumable"
state="/var/lib/rumable"
site_id="replace with the original site ID"

Windows (administrator terminal):

$rumable = Read-Host 'Enter the full path to the rumable.exe used by the original deployment'
$state = Join-Path $env:ProgramData 'Rumable'
$siteId = Read-Host 'Enter the original site ID'

Update an Onboarded Site¶

First back up the original TOML, the complete state directory, and the server configuration, then choose the workflow according to the saved TOML format:

Auto-Discovery Configuration¶

Use the saved TOML as the source of truth. Return to the configuration page and fill in the complete parameters, adjusting only the options you need to change while keeping the original sampling, replay, and SDK settings. After reading and verifying the selected installation package, save the new TOML, run the generated command on the original server, and select the original website and binding. Re-running the one-click command also installs the selected package, so verify its SDK version as well.

If the original deployment uses a custom state directory, or you only want to apply the modified discovery configuration with the current CLI, run the following commands, replacing the configuration path with the actual saved file.

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 'Failed to apply the configuration. Check the cause first.' }

Discovery against the same target reuses the original ID, URL, and path scope. Verify that the output site ID matches the original record; do not use a new manual ID to take over an existing deployment. The discovery configuration cannot be passed directly to enable.

Complete Site Configuration¶

Edit the original TOML, keep the original site ID and deployment target, and then run enable. Do not repeat init/render, and do not delete the state directory. Replace the configuration paths below with the original file.

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 'Failed to apply the configuration. Check the cause first.' }

After either method completes, run status/probe as described in Verify the Onboarding Result, and check the new page and the actual data. The SDK source, loading method, and RUM parameters are all updated through this workflow.

When adjusting the path scope or probePaths of an auto-created site, prepare a complete configuration based on the original ID, URL, and server target, verify the identity, and then run enable. Changing publicURL, the Nginx program/startup parameters, or the IIS site/application means migrating the deployment target and cannot be done with a normal configuration update.

How the SDK Is Updated¶

The same-domain SDK is fixed in the installation package and is not updated automatically in the background. Release maintainers synchronize and verify the SDK before publishing a new package; website administrators need to upgrade and apply it proactively. Merely replacing the CLI, reading latest, changing the business version, or enabling remoteConfiguration does not update the deployed same-domain SDK.

Upgrade steps:

1. Back up the original TOML, the complete state directory, and the server configuration, and keep the old CLI.
2. Select the new package from the release manifest, verify the digest, and install it to a new directory; verify rumable version and the version information inside the package.
3. Point rumable / $rumable to the new CLI, keep the original site ID and state directory; run enable or setup --discover according to the configuration type.
4. When IIS takes over an old deployment for the first time, it records pool ownership and recycles once; subsequent repeated operations with exactly the same configuration do not trigger additional recycling. First do a normal refresh on the original browser page with the cache preserved, confirm that the current initialization script is obtained, and then run status/probe.
5. If the CDN, proxy, or Service Worker still returns the old HTML, save the response evidence and then handle it according to the corresponding cache policy. Then check the new page, new sessions, SDK download, original business functions, actual RUM data ingestion, and replay.

When the official mutable CDN updates first, check/enable/probe in the old CLI may fail due to digest mismatches. In this case, use a new package containing the matching SDK, or switch to immutable CDN files consistent with the current package; do not disable digest checking to bypass the mismatch. Pages that are already open will not have the SDK hot-replaced, and external workers must also keep versions consistent.

IIS Application Pools and Configuration Application¶

The target application must use a started, exclusive application pool, and child applications must also have their own pools. Enable, update, disable, historical rollback, and failure recovery first write the configuration and save the recovery state, then recycle the target pool and wait for the old worker process to exit, and finally check HTTP. Identical repeated installations or disables do not trigger additional recycling.

Recycling may lose in-process sessions, so arrange a suitable maintenance window. The tool does not assign application pools automatically, does not recycle shared pools, and does not restart the entire IIS. After onboarding, do not directly change the managed pool name or add other applications to it; if adjustments are needed, first disable using the original deployment information and plan the migration to avoid triggering ownership drift protection.

IIS onboarding disables static and dynamic compression for the selected application, and disable restores the original local settings or inheritance relationships. File-level compression overrides, backend compression, or external HTML caches may still affect pages. When enabled, managed HTML navigation requests that reach the target IIS have their old conditional validation headers cleared to avoid reusing the old body; excluded paths and public SDK resources do not use this handling.

If the old worker process does not exit promptly, the operation may fail and attempt recovery; if the recovery is incomplete, the transaction is retained. First check long-running requests and the target pool status, keep the complete output and state backup, and after the conditional recovery, run rollback with the original site ID and state directory. Do not delete the transaction, manually edit the state, or force-kill business processes to bypass the checks.

Operation probe failures are recorded in last-operation-probe-failure.json in the site's private state directory; recovery probe failures are saved separately in last-recovery-probe-failure.json. Save these files before retrying and verify this operation by time; after automatic recovery succeeds, old failure records remain, so the file existing does not mean the current state is still failing. Provide redacted copies to support personnel; do not expose complete state backups or tokens.

Disable, Rollback, and Uninstall¶

Disable Collection¶

First set the variables at the top of this page. If you only want to stop collection, run disable and the check.

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 'Disable failed. Check the cause first.' }
& $rumable probe --state-dir $state --site $siteId

Disable only stops new HTML injection and keeps the resources for old pages. Existing pages and old HTML caches may continue running the SDK. Compression, cache, or request header adjustments made during Nginx auto-attachment may also remain.

Disabling on IIS restores the original compression settings and inheritance relationships and recycles the target pool. After a normal refresh, newly loaded HTML should not contain the injection from this deployment. After the business cache policy is restored, 304 may be returned; verify whether the actually reused body still contains the injection. Old hashed scripts and public resource mappings are kept for old pages.

Restore the Previous Deployment¶

Rollback is a separate operation that may re-enable collection. Run it only when you need to restore the previous successful deployment; do not run it right after a normal disable.

Linux:

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

Windows:

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

When an interrupted transaction exists, rollback first attempts to recover the transaction; otherwise, it switches between the current snapshot and the previous successful snapshot. It is not an unbounded history rollback and does not automatically restore the TOML on disk. Running enable again after a rollback reapplies the current TOML, so verify the desired configuration at the same time, and then check the status, page, and data.

Complete Uninstall¶

First disable and clear the old HTML caches, then preview the uninstall scope.

Linux:

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

Windows:

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

Review the preview results; after confirming the targets and the scope of changes, run the uninstall.

Linux:

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

Windows:

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

uninstall restores managed settings, removes resource mappings, and archives the state. After that, the site cannot be directly restored with a normal rollback. It does not automatically delete the CLI or a web server installed by the user.

When undoing only the initial automatic Nginx attachment on Linux, first run disable, then preview with rollback --attachment --dry-run; after confirming, run rollback --attachment. External modifications or other sites later attached to the same file may prevent recovery; review the differences and do not delete backups or state files to force through.

Manually added Nginx includes have no automatic attachment backup, so their removal by rollback --attachment cannot be guaranteed. Follow the installation package guide to remove the manual include added this time and restore the relevant directives; after the configuration check and reload succeed, archive the managed state. Do not directly delete directories still referenced by the server.

Frequently Asked Questions¶

Rumable's default automatic onboarding handles browser RUM; server-side OTel is a separate capability. Do not install or modify server-side Trace components just to onboard the Web SDK.