Rumable のアップグレード、ロールバック、トラブルシューティング¶

このページは、すでに導入済みのサイトを対象としています。操作前に、元の設定、サイト ID、CLI パス、状態ディレクトリ、Web サーバー設定のバックアップを保持してください。初回導入はインストール手順、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、サーバーターゲットに基づいて完全な設定を作成し、ID を確認してから 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 が初めて旧デプロイを引き継ぐときにプールの帰属を記録し、1 回だけリサイクルします。以後、設定が完全に同じ繰り返し操作では追加のリサイクルは行われません。まず元のブラウザページでキャッシュを保持したまま通常更新を行い、現在の初期化スクリプトを取得できたことを確認してから、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 リソースにはこの処理は適用されません。

旧ワーカーがなかなか終了しない場合、操作は失敗し、復元を試みる可能性があります。復元が不完全な場合は、トランザクションを保持してください。まず長時間リクエストと対象プールの状態を確認し、完全な出力と状態バックアップを保持してから、復元の条件が整った場合に元のサイト 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 やユーザーが自分でインストールした Web サーバーを自動的に削除しません。

Linux Nginx の初回自動アタッチのみを取り消す場合は、まず disable を実行し、rollback --attachment --dry-run でプレビューしてから、確認後に rollback --attachment を実行します。外部による変更や、後から同じファイルにアタッチされた他のサイトが復元を妨げる可能性があるため、差分を確認してください。バックアップや状態ファイルを削除して強行しないでください。

手動で追加した Nginx include には自動アタッチのバックアップがないため、rollback --attachment による取り消しは保証できません。インストールパッケージのガイドに従って、今回の手動 include を削除し、関連ディレクティブを復元してから、設定チェックとリロードが成功した後に管理対象状態をアーカイブしてください。サーバーから参照されているディレクトリを直接削除しないでください。

よくある質問¶

Rumable のデフォルトの自動導入はブラウザ RUM を処理します。サーバーサイド OTel は独立した機能です。Web SDK を導入するために、サーバーサイドの Trace コンポーネントを一緒にインストールしたり変更したりしないでください。