Rumable で Web RUM をワンクリック導入¶

Rumable は、Nginx または IIS を使用して、Web サイトが返す HTML に Web RUM スクリプトを追加します。Web サーバーを管理でき、フロントエンドのソースコードを変更したくない Web サイトに適しています。SDK は訪問者のブラウザ上で実行され、データを Guance の OpenWay または設定した DataKit に直接送信します。CLI は導入完了後に終了するため、常駐型の収集サービスではありません。

初回導入には、設定の手書きが不要なワンクリック導入を推奨します。オフライン環境や段階的な確認を希望する環境では、手動インストールを使用します。SDK の配信元、読み込み方式、完全な TOML の例は設定説明を、導入済みサイトの更新と復旧は運用説明を参照してください。インストールと日常利用に Git、Go、Node.js、データベースは不要です。

ワンクリック導入（推奨）¶

設定ページを開く → アプリパラメータを入力 → インストールコマンドをコピー → Web サーバーで実行 → サイトを選択 → データを検収。 自分で TOML を記述する必要も、CLI を事前にインストールする必要もありません。コマンドが対応プラットフォームの CLI をダウンロード、検証、インストールし、サイトを導入します。サーバーはダウンロード URL にアクセスでき、下記のサーバー要件を満たす必要があります。

ステップ1: ページでパラメータを入力¶

まず「RUM > アプリリスト」で Web アプリを作成し、アプリ ID とデータ送信パラメータを取得して、サーバー要件を確認します。

ワンクリック導入設定ページを開き、アプリパラメータを入力して、プラットフォームを選択します。まずはデフォルトの同一ドメイン・非同期で検証を完了します。初回検証では、セッションサンプリング 100%、リプレイオフを推奨します。

「Linux / Nginx + サイトと同一ドメイン + 非同期」を例に、ページで次のように入力します。

同じフローで、同一ドメイン/CDN と同期/非同期の4つの組み合わせに対応しており、TOML の手書きは不要です。CDN を選択する場合は、SDK の HTTPS スクリプトアドレスを入力します。SDK を初期化した後に後続の業務スクリプトを実行する必要がある場合は「同期」を選択します。具体的な違いは SDK 配信元と読み込み方式 を参照してください。

ステップ2: リリースバージョンを読み取り、コマンドをコピー¶

1. 「リリースバージョンを読み取る」をクリックし、ページに Rumable と Web SDK のバージョンが表示されることを確認します。
2. TOML をダウンロードして保管します。後続の変更や復旧に使用します。手動で編集する必要はありません。
3. 「インストールコマンド」に切り替えて、ページで生成された完全なコマンドをコピーします。コマンドをコピーするだけではサーバーは変更されません。実行して初めて導入が開始されます。

コマンドには入力した設定が含まれるため、他人のコマンドは使用できません。以下は、自動検出による導入のワンコマンドの構成のみを示しています。インストーラーURL、配信ディレクトリ、エンコード設定はすべてページで入力します。プレースホルダーの例を直接実行しないでください。 実際に実行するときは、ページで生成された完全なコマンドをコピーしてください。バージョン番号を手動で変更する必要はありません。

ステップ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 をインストールし、設定を読み取り、サイトを検出します。候補が1つだけの場合は自動的に選択されます。サイトやバインドが複数ある場合は、ターミナルのプロンプトに従って対象を選択し、必要に応じてアクセス URL を補足するか、圧縮調整を確認します。ワンクリックインストーラーには導入の確認が含まれています。コマンドを実行するとアプリケーションの変更に同意したことになります。対象を選択し、必要なプロンプトに応答すると、ツールは直接注入と HTTP 検証を実行します。

ワンクリック導入でも、曖昧さがある場合はサイトを選択する必要があります。最初のサイトをデフォルトで変更することはありません。また、Nginx、IIS、URL Rewrite を自動インストールすることもありません。対象をカスタマイズする場合は、ページで「サイトとパスを手動指定」をオンにしてワンコマンドを生成できます。複雑な設定やオフラインサーバーの場合は、手動インストールを使用します。

ステップ4: 結果を保存して検収¶

ターミナルに RUM setup complete と表示されたら、出力されたサイト ID と URL を記録します。高度な手動モードでは、設定内の id と publicURL を使用します。選択したバージョン、ダウンロードした TOML、および下の表で特定した CLI パスと状態ディレクトリを保存します。状態ディレクトリは完全にバックアップし、Nginx が Backup: を出力した場合は、そのパスを別途記録します。続いて、導入結果の確認に従って、ブラウザでの収集と実際のデータ取り込みを確認します。検収に合格すれば初回導入は完了です。手動インストールを実行する必要はありません。

設定ページはローカルブラウザで設定を生成するため、アプリ設定がダウンロードサイトに送信されることはありません。コマンド内の Base64 は単なるエンコードであり、暗号化ではありません。Client Token を含む完全なコマンドを公開しないでください。ワンクリックインストーラーは一時 TOML を削除するため、ページでダウンロードした設定は保管してください。

デフォルトのインストール場所：

表のバージョンは、設定ページに表示される今回選択したバージョンになります。ワンクリックインストールでは CLI が PATH に自動追加されることはありません。状態ディレクトリには、デプロイ、復旧、帰属情報が保存されるため、保持し、バックアップしてください。以降の操作では、元のサイト ID と状態ディレクトリを引き続き使用し、元の設定タイプに応じた更新方法に従ってください。

固定エントリとインストールパッケージの選択¶

• オンライン設定ページ：設定を入力し、インストールコマンドを生成します。
• リリースマニフェスト：推奨インストールパッケージ、組み込み SDK、ダウンロードファイル、検証情報を読み取ります。

設定ページはマニフェストを一度読み取ると、コマンドをそのリリースのインストーラーとインストールパッケージに向け、対応するダイジェストで検証します。ドキュメントのエントリは常に latest を使用します。具体的なバージョン、パッケージ名、検証情報はリリースプロセスで更新されるため、ユーザーがドキュメント内でバージョン番号を置き換える必要はありません。

latest を読み取るのは、今回使用するインストールパッケージを決めるためだけであり、導入済みのサイトを自動的にアップグレードするものではありません。導入済みサイトでは、インストール時に記録された CLI パスと状態ディレクトリを引き続き使用します。アップグレード時は、アップグレード手順に従って新しいパッケージを選択して適用してください。

導入前の準備とサーバー要件¶

1. 「RUM > アプリリスト」で Web アプリを新規作成し、applicationId を取得します。
2. データ送信方法を1つ選択します。OpenWay は site とブラウザ用 clientToken を使用します。DataKit への直接接続は datakitOrigin を使用します。詳細は Web アプリの導入 を参照してください。管理 API Key は使用しないでください。
3. サイトで同じ SDK が重複導入されていないことを確認します。業務コードに組み込まれている導入も手動で確認する必要があります。
4. HTTP 200 の HTML を直接返す検収用 URL を用意します。ページには標準の <head> 開始タグが必要です。リダイレクトページ、ログインページ、ダウンロード URL で代用しないでください。
5. Web サーバーの設定をバックアップし、操作権限とメンテナンスウィンドウを確認します。有効化すると、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 の互換性要件 を満たす必要があります。

オフラインまたは手動インストール¶

インターネットに接続されたマシンで、リリースマニフェストから OS、CPU、モダン/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 導入後は、元のブラウザページでキャッシュを保持したまま通常の更新を1回実行してください。ハードリフレッシュや Disable cache は使用しないでください。ホームページとその他の主要な HTML ページを確認します。HTTP 200 が返り、現在の初期化スクリプトが1つだけ含まれ、業務コンテンツが正常である必要があります。自動検出では、デフォルトでは通常ホームページのみをチェックします。他のテンプレートも対象にする場合は、対応する 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

検収はレイヤーごとに確認します。

probe は HTTP 注入とリソースへの到達可能性を検証するものであり、ブラウザ SDK は実行しません。模擬の受信側が成功を返しても、実際の取り込み確認の代わりにはなりません。完全な検収後に、サンプリングとリプレイを調整してください。