Web アプリケーションの導入¶

このページの設定を完了すると、Browser RUM SDK はページの View、リソースリクエスト、フロントエンドエラー、ユーザー操作を自動的に収集し、Guance にデータを送信します。

導入経路の選択¶

まずアプリケーションの形態に応じて導入口を選択します。View の重複設定や、サーバーサイドレンダリングの段階でブラウザ API にアクセスすることを避けられます。

導入情報の準備¶

1. 「RUM > アプリ一覧 > アプリを作成 > Web」に移動します。
2. アプリを作成し、コンソールで生成された applicationId、env、version などの設定を取得します。

3. データ送信方法を選択します：

4. パブリック OpenWay：site と clientToken を取得します。DataKit のデプロイは不要です。

5. DataKit 直結：datakitOrigin を準備します。DataKit で RUM コレクター を有効にし、パブリックネットワークからアクセス可能で、IP 地理情報データベースがインストールされた状態 に設定する必要があります。

送信方法¶

{
  applicationId: "<APPLICATION_ID>",
  datakitOrigin: "<DATAKIT_ORIGIN>"
}

{
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>"
}

SDK の導入¶

NPM での導入¶

フロントエンドプロジェクトに SDK をインストールして読み込みます：

npm install @cloudcare/browser-rum @cloudcare/browser-core

プロジェクトで SDK を初期化します：

import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN 同期読み込み¶

HTML ファイルにスクリプトを追加します：

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

CDN 非同期読み込み¶

HTML ファイルにスクリプトを追加します：

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.guance.com/browser-sdk/v3/dataflux-rum.js",
    "DATAFLUX_RUM"
  )
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
  })
</script>

上記の例はパブリック OpenWay を使用しています。DataKit 直結を使用する場合は、site と clientToken を削除し、代わりに datakitOrigin を設定してください。

軽量版 RUM SDK¶

RUM SDK 3.3.3 から軽量版が利用できます。軽量版はフル版と同じ初期化方法に対応し、View、Resource、Long Task、Error、Action、ユーザーとグローバル Context、カスタムイベント、分散型トレーシングなどの通常の RUM 機能をサポートします。ページ録画が不要で、フロントエンドのバンドルサイズを抑えたいアプリケーションに適しています。

NPM での導入¶

通常の RUM パッケージを同じバージョンの軽量パッケージに置き換えます：

npm install @cloudcare/browser-rum-slim @cloudcare/browser-core

import { datafluxRum } from "@cloudcare/browser-rum-slim"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN での導入¶

同期読み込み・非同期読み込みの方法はフル版と同じです。スクリプトファイル名を軽量版の対応ファイルに置き換えるだけです。以下は同期読み込みの例です：

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum-slim.js"
  type="text/javascript"
></script>
<script>
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

フル版との機能の違い¶

軽量版には以下の機能は含まれません：

• Session Replay、および startSessionReplayRecording()、stopSessionReplayRecording()、isRecording() などの録画 API。
• Canvas 2D、WebGL/WebGL2 の録画、および snapshotCanvas() などの Canvas API。
• compressIntakeRequests による送信データの圧縮と、対応する Worker。

軽量版では、sessionReplaySampleRate、sessionReplayOnErrorSampleRate、replayCanvasEnabled は強制的に無効になり、compressIntakeRequests は強制的に false になります。導入時はこれらの設定を渡さないでください。また、workerUrl や replayCanvasWorkerUrl を設定する必要もありません。後でセッションリプレイ、Canvas 録画、圧縮送信が必要になった場合は、NPM パッケージまたは CDN ファイルをフル版に戻してください。他の基本初期化パラメータはそのまま使用できます。

導入の確認¶

1. SDK を導入したページを開き、ページ遷移、ボタンクリック、API リクエストをそれぞれ 1 回実行します。
2. ブラウザの開発者ツールの Network で /v1/write/rum をフィルタリングし、成功した送信リクエストが存在することを確認します。
3. Console で、Application ID is not configured、datakitOrigin or site is not configured などの初期化エラーがないことを確認します。
4. 「RUM > アプリ一覧」に移動し、該当する Web アプリを開いて、エクスプローラーで service、env、version をフィルタリングし、View、Resource、Action のデータが存在することを確認します。

よく使うオプション設定¶

基本データの確認ができたら、必要に応じて他の機能を有効にします：

分散型トレーシング設定（オプション）¶

NPM + TypeScript で導入する場合、traceType には、対応するブランドの browser-core パッケージからインポートした TraceType 列挙型を使用する必要があります：

import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  allowedTracingUrls: ["https://api.example.com"],
  traceType: TraceType.DDTRACE
})

TraceType.DDTRACE のランタイム値は引き続き "ddtrace" です。CDN 導入にはモジュールのインポートがなく、明示的に設定する場合は対応するランタイム文字列を使用します。分散型トレーシングを有効にした後は、API サーバー側で対応する Trace Header を許可する必要もあります。詳細は APM と RUM の関連付け を参照してください。

通常の Session がサンプリングに該当しない場合でも、Trace Header をバックエンドに渡す必要がある場合は、allowTraceHeaderWithoutSession を明示的に有効にできます：

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 0,
  sessionOnErrorSampleRate: 0,
  allowedTracingUrls: ["https://api.example.com"],
  allowTraceHeaderWithoutSession: true
})

有効にすると、SDK は allowedTracingUrls に一致する XHR と Fetch リクエストにのみ Trace Header を挿入します。この設定は RUM Session を作成したり強制有効化したりせず、サンプリングされなかった Session の View、Error、Resource、Action データも送信しません。API サービスは、選択した traceType に対応するリクエストヘッダーを引き続き許可する必要があります。また、クロスオリジンリクエストでは CORS を正しく設定する必要があります。

パラメータ設定¶

初期化パラメータ¶

low、medium、high の文字列プリセットを使用しない場合、Canvas の自動スケジューリングのベースラインは、sampling 2、Canvas ごとの目標 interval 250 ms、cooldown 250 ms、unchanged backoff 3000 ms、failure backoff 5000 ms、1 ラウンドあたり最大 2 つの Canvas です。文字列プリセットはこれらの予算とエンコード品質を同時に置き換えます。複数の Canvas は公平なローテーションとグローバルな収集予算の制限も受けます。明示的な個別設定は、プリセット内の対応する値を上書きします。完全な preset マトリックスは Canvas 録画マニュアル を参照してください。

上記の高頻度スケジューリングのベースラインは Canvas 2D 向けです。WebGL プラグインは、interval/cooldown を明示的に設定しない場合、より保守的な GPU 読み戻しのペースを引き続き使用します。明示的な個別設定を行った場合のみ、それぞれ上書きされます。

site パラメータの処理¶

ランタイムでの Session 制御¶

RUM SDK 3.3.6 で startSession() が追加されました。呼び出すと、現在の Session がすぐに終了し、現在のサンプリング設定に従って Session が再開されます。次のユーザー操作を待つ必要はありません：

datafluxRum.startSession()

ランタイムの sessionSampleRate を同時に上書きすることもできます：

datafluxRum.startSession({
  sessionSampleRate: 100,
})

サンプリング率は 0 から 100 の間で指定する必要があります。この上書き値は、今回の Session と、その後自動的に継続される Session に適用されます。フル RUM パッケージと軽量 RUM パッケージの両方でこの API をサポートしています。詳細な仕様とユースケースは ランタイムで Session を再開する を参照してください。

必要に応じて高度な機能を有効にする¶

エラーセッションのイベントのみを収集する¶

ページでエラーが発生すると、SDK は自動的に次の処理を実行します：

• 継続的な記録：エラー発生時から、セッションの全ライフサイクルのデータを完全に記録します。
• 正確な補償：独立したサンプリングチャネルにより、エラーシナリオを漏れなく記録します。

設定方法¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 0,
    sessionOnErrorSampleRate: 100
  })

上記の例はパブリック OpenWay を使用しています。DataKit 直結の場合は、基本導入の例に従って送信アドレスのフィールドを置き換えてください。

データ圧縮¶

大量の静的リソース（JS、CSS、画像など）を収集し、全量収集を有効にしている場合、SDK は初期化後に多くのデータを生成する可能性があります。これによりリクエストが滞留し、アプリケーションのスレッド状態に影響を与える可能性もあります。

compressIntakeRequests: true を設定すると、SDK は Web Worker で deflate を使用して送信データを圧縮し、リクエストサイズとリクエスト数を削減します。

設定例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    compressIntakeRequests: true
  })

注意事項¶

1. データ圧縮ロジックは Web Worker で実行されます。CSP セキュリティポリシーを有効にしている場合は、worker-src で blob: を許可する必要があります。詳細は CSP セキュリティポリシー を参照してください。
2. SDK は、workerUrl 設定項目を使用して、自分でホストする Worker アドレスを指定できます。
3. この機能を使用するには、SDK バージョンが >= 3.2 である必要があります。

カスタムデータとイベント¶

基本導入ページでは、すべてのパブリック API を重複して説明しません。目的に応じて対応するページに移動すると、CDN、NPM、および完全なパラメータの例を確認できます。

• ユーザー操作の追跡：クリックの自動収集、Action 名の定義、カスタム Action の追加。
• カスタムユーザー ID：ログイン後にユーザーを設定し、ログアウトやアカウント切り替え時にユーザー情報をクリアします。
• グローバルコンテキスト：後続のすべての RUM イベントに安定したビジネスディメンションを追加します。
• カスタム Action の追加：ページのクリックでは表現できないビジネス操作を記録します。
• カスタム Error の送信：捕捉済み、またはビジネス側で主体的に特定した例外を送信します。

Web セッションリプレイ¶

録画を有効にする¶

SDK の初期化後、startSessionReplayRecording() メソッドを呼び出して、セッションリプレイの録画を開始します。ユーザーのログイン後など、特定の条件で録画を開始することもできます。セッション録画を有効にする。

エラー関連のセッションリプレイデータのみを収集する¶

ページでエラーが発生すると、SDK は自動的に次の操作を実行します：

• 遡及収集：エラー発生前の 1 分間の完全なページスナップショットを記録します。
• 継続録画：エラー発生時からセッション終了まで記録し続けます。
• インテリジェントな補償：独立したサンプリングチャネルにより、エラーシナリオを漏れなく記録します。

設定例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 100,
    sessionReplaySampleRate: 0,
    sessionReplayOnErrorSampleRate: 100
  })

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()

注意事項¶

• セッションリプレイは iframe、動画、音声の再生コンテンツを記録しません。Canvas はデフォルトでは収集されないため、replayCanvasEnabled を個別に設定する必要があります。WebGL/WebGL2 は SDK 3.3.7 から利用可能で、RUM メインパッケージのバージョンが >= 3.3.7 である必要があります。互換性のある browser-rum-webgl プラグインを追加でインストールして登録する必要もあります。プラグインとメインパッケージには同じ SDK リリースバージョンを使用することをお勧めします。詳細は Canvas 録画マニュアル を参照してください。
• リプレイ時に静的リソース（フォント、画像など）へ正常にアクセスできるようにするには、CORS ポリシーの設定が必要になる場合があります。
• CSS スタイルとマウスホバーイベントをサポートするには、CSSStyleSheet インターフェースから CSS ルールにアクセスできることを確認してください。

録画状態の確認¶

window.DATAFLUX_RUM.isRecording() を呼び出して、現在のページが録画中かどうかを確認します。また、セッションリプレイエクスプローラーで、該当する Session にリプレイデータが生成されていることを確認します。本番環境では、ビジネス要件に応じて sessionReplaySampleRate を調整してください。