Canvas 録画ユーザーガイド¶

概要¶

Guance Browser RUM は、Session Replay での Canvas 2D 画面の録画をサポートしています。SDK 3.3.7 以降で WebGL/WebGL2 を録画するには、追加で WebGL Replay プラグインをインストールする必要があります。

Canvas 2D 録画設定は SDK 3.3.0 から利用可能です。WebGL Replay は SDK 3.3.7 から提供され、RUM メインパッケージのバージョンが >= 3.3.7 である必要があります。WebGL プラグインと RUM メインパッケージは同じ SDK リリースバージョンを使用することを推奨します。Canvas 2D の >= 3.3.0 や汎用 plugins 設定のバージョン要件だけでは、WebGL が利用可能かどうかを判断できません。

まず最も重要な点を説明します。

replayCanvasEnabled を設定するだけでは不十分です。

Canvas 録画を実際に有効にするには、少なくとも以下の前提条件をすべて満たす必要があります。

• Session Replay のサンプリングが有効になっている
• つまり sessionReplaySampleRate > 0 であるか、sessionReplayOnErrorSampleRate に該当している
• Session Replay の録画が開始されている
• つまり startSessionReplayRecording() を呼び出している
• Canvas 録画が有効になっている
• つまり replayCanvasEnabled: true
• ページ内の対象要素が Canvas 2D であること。WebGL/WebGL2 の場合は WebGL Replay プラグインの登録も必要
• manual モードの場合、ビジネスコードで snapshotCanvas(canvas) を明示的に呼び出す必要がある

現在のバージョンの機能範囲は次のとおりです。

• 手動トリガー録画をサポート
• 自動録画をサポート
• 自動録画は 2 つの正式なパスをサポート:
• snapshot sampling
• higher-fidelity auto recording
• RUM メインパッケージは Canvas 2D を直接サポート
• オプションの WebGL Replay プラグインは WebGL/WebGL2 の予算内ピクセルスナップショットをサポート
• 録画結果は Session Replay イベントストリームに取り込まれる

現在のバージョンでカバーされない範囲:

• WebGL コマンドレベルのリプレイ、フレーム単位の動画録画
• OffscreenCanvas
• 複雑な 2D シーンすべてを完全に同じように再現すること

クイック選択¶

最小限の動作設定¶

以下は、現在の最小限の動作設定です。実際に導入する際は、ここからコピーして、シナリオに応じて項目を追加することを推奨します。

1. 手動録画: 最も安定、最も推奨¶

この設定は以下に適しています。

• 画面がいつ安定するか把握している場合
• 重要な瞬間だけフレームを補完したい場合
• コストを可能な限り制御したい場合

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

その後、ビジネスコードで明示的にフレームを補完します。

await datafluxRum.snapshotCanvas(canvasElement)

この設定で明示的に指定する必要があるのは以下です。

• sessionReplaySampleRate
• replayCanvasEnabled

同時に明示的に指定することを推奨するのは以下です。

• replayCanvasMode: 'manual'
• replayCanvasQuality: 'medium'

2. 自動スナップショット: より保守的な自動録画¶

この設定は以下に適しています。

• ビジネス側でフレーム補完のタイミングを手動で制御しにくい場合
• 安定性とコストを重視する場合
• 自動フレーム補完がフレーム単位でなくても許容できる場合

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

この設定で明示的に指定することを推奨するのは以下です。

• replayCanvasEnabled: true
• replayCanvasMode: 'auto'
• replayCanvasSampling: 2
• replayCanvasQuality: 'medium'

replayCanvasSampling を明示的に指定しなくても SDK は数値モードを使用しますが、導入説明でデフォルト値に依存することは推奨しません。明確に指定してください。

3. 自動高再現度録画¶

この設定は以下に適しています。

• 自動モードで実際の描画プロセスに近い動作を希望する場合
• ページが主に 2D Canvas で構成されている場合
• 複雑なシーンで自動的にスナップショットにフォールバックしても許容できる場合

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 'all',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

この設定で明示的に指定する必要があるのは以下です。

• replayCanvasEnabled: true
• replayCanvasMode: 'auto'
• replayCanvasSampling: 'all'

WebGL/WebGL2 プラグイン導入¶

WebGL の実装は RUM メインパッケージに含まれていません。通常の DOM および Canvas 2D Replay にはプラグインのインストールは不要です。WebGL/WebGL2 Replay が必要なアプリケーションのみ、追加で導入します。RUM メインパッケージのバージョンは >= 3.3.7 である必要があり、プラグインとメインパッケージは同じ SDK リリースバージョンを使用することを推奨します。

WebGL プラグインは、replayCanvasEnabled: true かつ replayCanvasMode: 'auto' の場合にのみデータを収集します。これは描画境界上の予算内ピクセルスナップショットを記録するものであり、WebGL コマンドのリプレイやフレーム単位の動画ではありません。

NPM¶

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

import { datafluxRum } from '@cloudcare/browser-rum'
import { webglReplayPlugin } from '@cloudcare/browser-rum-webgl'

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  sessionReplaySampleRate: 100,
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 1000,
  replayCanvasQuality: 'medium',
  plugins: [webglReplayPlugin()]
})

datafluxRum.startSessionReplayRecording()
startWebGLEngine()

CDN¶

両方のスクリプトを DATAFLUX_RUM.init() の前にロードする必要があります。

<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"></script>
<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum-webgl.js"></script>
<script>
  DATAFLUX_RUM.init({
    applicationId: '<YOUR_APPLICATION_ID>',
    datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
    sessionReplaySampleRate: 100,
    replayCanvasEnabled: true,
    replayCanvasMode: 'auto',
    replayCanvasSampling: 2,
    replayCanvasAutoInterval: 1000,
    replayCanvasQuality: 'medium',
    plugins: [DATAFLUX_RUM_WEBGL.webglReplayPlugin()]
  })

  DATAFLUX_RUM.startSessionReplayRecording()
  startWebGLEngine()
</script>

プラグインの初期化に失敗した場合、またはブラウザが必要な機能をサポートしていない場合は、WebGL 収集のみが無効になります。通常の DOM、Canvas 2D、およびその他の RUM データの収集は続行されます。

設定が必要な項目¶

目的が「とにかく Canvas 録画を動作させる」だけの場合、最低限以下のパラメータを確認してください。

満たすべき前提条件¶

• sessionReplaySampleRate
• Replay がサンプリングされることを保証する必要があります。そうでなければ Canvas 録画は機能しません。
• startSessionReplayRecording()
• init() だけでは不十分です。実際に Replay 録画を開始する必要があります。
• replayCanvasEnabled: true
• これを有効にしないと、Canvas 録画は完全に無効になります。

手動モードで必須の設定¶

• replayCanvasEnabled: true
• replayCanvasMode: 'manual' を明示的に記述することを推奨
• ビジネスコードで snapshotCanvas(canvas) を呼び出す必要があります

自動モードで必須の設定¶

• replayCanvasEnabled: true
• replayCanvasMode: 'auto'
• replayCanvasSampling を明示的に記述することを推奨
• 数値: 自動スナップショット
• 'all': より高再現度の自動録画

replayCanvasWorkerUrl を設定するタイミング¶

このパラメータは「機能のオン/オフ」ではなく、デプロイパラメータです。

以下のシナリオでのみ設定が必要です。

• サイトの CSP で worker-src blob: が許可されていない場合
• Canvas スナップショットエンコードワーカーを個別にホストしたい場合
• Canvas エンコードがインライン blob worker を使用しないことを明確にしたい場合

典型的な記述:

datafluxRum.init({
  // ...
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

注意:

• replayCanvasWorkerUrl は Canvas スナップショットエンコードにのみ影響します
• 元の workerUrl を代替するものではありません
• 現在のフレームがスナップショットエンコードを使用しない場合、Canvas worker は使用されません

モードの違い¶

manual¶

特徴:

• ビジネス側がフレーム補完のタイミングを主体的に決定します
• 重複フレームの重複除去は行いません
• 「重要な瞬間にフレームを補完する」のに最適です

適しているケース:

• グラフのレンダリング完了時
• ゲームのリザルト画面
• ホワイトボードの保存時
• アニメーション終了後の最終画面取得時

auto¶

特徴:

• SDK が自動でフレームを補完します
• 具体的な補完方法は replayCanvasSampling によって決まります
• ページがバックグラウンドに移動すると録画を一時停止し、フォアグラウンドに戻ると再開します
• shouldRecordCanvas() で数値の優先度を返すことで、重要な Canvas を優先的に録画できます

replayCanvasSampling の正式な意味:

• 正の数（2 から開始推奨）: 自動スナップショットパスを選択します。Canvas 2D の場合、数値自体が収集頻度を制御するわけではありません。
• 'all': より高再現度の自動録画。描画プロセスを可能な限り保持します。複雑なシーンでは自動的にスナップショットにフォールバックする可能性があります。

自動スナップショットの収集リズムは、replayCanvasAutoInterval、cooldown、backoff 設定によって制御されます。WebGL プラグインもこれらの予算制限の対象となります。'all' を指定した場合でも、WebGL はピクセルスナップショットを使用します。'all' は Canvas 2D がコマンドキャプチャを試みることのみを許可します。

簡単な選択の推奨:

• 設定方法がわからない場合: まず replayCanvasSampling: 2 を使用
• コストを重視する場合: replayCanvasAutoInterval を増やす
• スナップショットの連続性を重視する場合: replayCanvasAutoInterval を徐々に減らす
• Canvas 2D の描画再現度を重視する場合: 'all' が必要かどうかを評価
• 複雑さとデータコストの増加を明確に受け入れられる場合にのみ、'all' を使用

適しているケース:

• ビジネス側でフレーム補完のタイミングを手動で制御しにくい場合
• ページに少数から中規模の 2D Canvas がある場合
• コストと再現度のバランスを取りたい場合
• 複数のグラフがあるページで、主要なグラフのみを優先的に録画したい場合

ユースケース¶

以下のようなケースに適しています。

• ビジネス側で画面がいつ安定するか把握している場合
• 重要な操作の後に手動で Canvas 画面を 1 回キャプチャしたい場合
• Session Replay で 2D Canvas の視覚結果の一部を再現できるようにしたい場合

以下のようなケースには適していません。

• 高頻度アニメーションのフレーム単位録画
• すべてのフレームを厳密に再現する動画のようなリプレイ
• OffscreenCanvas や WebGL コマンドレベルの再現に依存するシーン

有効化方法¶

NPM¶

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

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 100,
  trackUserInteractions: true,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

CDN¶

<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: '<YOUR_APPLICATION_ID>',
      datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
      service: 'browser',
      env: 'production',
      version: '1.0.0',
      sessionSampleRate: 100,
      sessionReplaySampleRate: 100,
      trackUserInteractions: true,

      replayCanvasEnabled: true,
      replayCanvasMode: 'manual',
      replayCanvasQuality: 'medium'
    })

  window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

設定項目の説明¶

日常的な導入では、まず以下の 6 つの設定項目に注目してください。

• replayCanvasEnabled
• replayCanvasMode
• replayCanvasSampling
• replayCanvasQuality
• replayCanvasAutoInterval
• shouldRecordCanvas

その他のパラメータは高度な上書き項目です。デフォルトのポリシーが現在のページに適さないと確認できた場合にのみ、さらに調整を進めてください。

replayCanvasEnabled¶

• 型: boolean
• デフォルト値: false

Canvas 録画機能を有効にするかどうか。

常に明示的に設定することを推奨します。デフォルトで無効の場合、既存の通常の Session Replay ロジックには影響しません。

replayCanvasMode¶

• 型: string
• 現在サポート: 'manual' | 'auto'
• デフォルト値: 'auto'

Canvas 録画モードを指定します。

• manual: ビジネスコードが適切なタイミングで snapshotCanvas() を明示的に呼び出します
• auto: SDK が自動的にフレームを補完します。具体的なポリシーは replayCanvasSampling によって決まります

replayCanvasSampling¶

• 型: number | 'all'
• デフォルト値: 数値モード

auto モードでの Canvas 録画ポリシーを指定します。

• 数値: スナップショットサンプリング
• 'all': より高再現度の自動録画

推奨:

• より安定、より保守的な方法を目指す場合: 数値モードを優先
• 実際の描画プロセスにより近づけたい場合: 'all' を使用

注意:

• 'all' を指定しても、すべてのシーンで完全に高再現度パスで録画されるわけではありません
• 特定の複雑なシーンでは、SDK は自動的にスナップショットにフォールバックします
• 数値自体は Canvas 2D の収集頻度を制御しません。リズムを調整する必要がある場合は、replayCanvasAutoInterval および cooldown/backoff 設定を使用します
• WebGL は常にプラグインのピクセルスナップショットパスを使用し、2D コマンドキャプチャには入りません

replayCanvasQuality¶

• 型: 'low' | 'medium' | 'high' | number
• デフォルト値: 0.4

Canvas スナップショットのエンコード品質。

文字列プリセットは、エンコード品質と自動収集予算の両方を調整します。単なる画像品質だけではありません。

low、medium、high を使用しない場合、表中の「文字列プリセット未使用」の列がランタイムのベースラインデフォルト値です。特定の設定を明示的に渡すと、その設定がプリセットの対応する値を上書きします。例えば、replayCanvasQuality: 'medium' と replayCanvasAutoCooldown: 800 を組み合わせた場合、cooldown のみ 800 ms を使用し、その他の項目は medium の値を使用します。

Canvas 2D の場合、replayCanvasAutoUnchangedBackoff は、シグネチャが継続して変化しない場合に、2 回の完全なエンコードチェック間のウィンドウを示します。ウィンドウ内でも、制限付きの 24x24 軽量シグネチャプローブが実行され、約 1000 ms まで徐々にバックオフします。変化が検出されると、完全なチェックウィンドウの終了を待たずに、目標のケイデンスに即座に復元します。WebGL は引き続き独立した、より保守的な GPU 読み取りリズムを使用します。

replayCanvasAutoInterval は、各 Canvas の目標収集間隔を示し、ページ全体の固定スキャン周期ではありません。複数の Canvas は公平にラウンドロビンされ、ラウンドあたりの数、同時実行数、およびグローバル収集予算の制限を受け続けます。そのため、複雑なダッシュボードでは、個々の Canvas の実際の頻度が目標値よりも低くなる可能性があります。デフォルトのグローバル上限は、1 秒あたり約 16.7 回のスナップショット試行で、メインスレッドとアップロードの負荷が Canvas の数に比例して増加するのを防ぎます。

上表の interval/cooldown は、Canvas 2D の自動スナップショットのベースラインです。WebGL プラグインは、GPU ピクセルを同期的に読み取る必要があります。明示的に設定されていない場合は、より保守的なリズムを引き続き使用します。デフォルトは 1000/1000 ms、low は 1500/3000 ms、medium は 1000/2000 ms、high は 700/1400 ms です。明示的な interval/cooldown が指定された場合のみ、それぞれ WebGL ポリシーを上書きし、2D の連続性を向上させる際に readPixels のコストが自動的に増大するのを防ぎます。

画像のエンコード品質のみを変更し、サンプリングとスケジューリングの予算は変更したくない場合は、0 から 1 の間の数値を渡してください。例: replayCanvasQuality: 0.4。replayCanvasSampling: 'all' の場合、コマンドフレーム自体は画像エンコードされませんが、フォールバックスナップショットはこの品質設定を使用します。

数値またはプリセットが高いほど:

• 画像品質が高くなります
• 通常、サイズが大きくなります
• Replay セグメントへの負荷も大きくなります

まずは medium から開始することを推奨します。

録画方法¶

API¶

現在の外部 API:

DATAFLUX_RUM.snapshotCanvas(canvasElement)

または NPM:

datafluxRum.snapshotCanvas(canvasElement)

戻り値は Promise で、resolve 後に以下を取得します。

{ ok: true }

または:

{ ok: false, reason: '...' }
`

現在発生する可能性のある `reason` は以下のとおりです。

- `not_recording`
- `replay_disabled`
- `invalid_mode`
- `not_canvas`
- `not_serialized`
- `detached`
- `rejected_by_should_record_canvas`
- `encode_too_large`
- `unchanged`
- `encode_failed`
- `observer_stopped`

### 最小限の例

```js
const canvas = document.getElementById('my-canvas')
const ctx = canvas.getContext('2d')

ctx.fillStyle = '#2563eb'
ctx.fillRect(20, 20, 160, 80)
ctx.fillStyle = '#0f172a'
ctx.font = '20px sans-serif'
ctx.fillText('Canvas Replay', 210, 70)

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.snapshotCanvas(canvas).then((result) => {
    if (!result.ok) {
      console.warn('snapshotCanvas failed:', result.reason)
    }
  })

推奨される呼び出しタイミング¶

以下のタイミングでの呼び出しを推奨します。

• 1 回の描画完了後
• 一連のアニメーション終了後
• ユーザーが重要な操作を完了した後

推奨されないタイミング:

• すべてのフレームで呼び出す
• 高頻度のタイマー内で呼び出す
• ページのアイドル時間外での大量のバッチ呼び出し

録画の有効条件¶

Canvas スナップショットを実際に Replay に取り込むには、以下をすべて満たす必要があります。

• init() が呼び出されている
• startSessionReplayRecording() が呼び出されている
• replayCanvasEnabled = true
• replayCanvasMode = 'manual' または 'auto'
• 渡された要素が HTMLCanvasElement である
• ノードが現在の DOM スナップショットに含まれている
• ノードがまだドキュメント内に存在している
• エンコード結果がサイズ制限を超えていない

これらの条件のいずれかが満たされない場合、今回のスナップショットは失敗するか、スキップされます。

shouldRecordCanvas の使い方¶

shouldRecordCanvas(canvas) は、「録画するかしないか」を制御するだけでなく、auto モードでの優先度を制御することもできます。

戻り値のルール:

• false を返す: この Canvas を録画しない
• 数値を返す: auto モードの優先度として扱われ、数値が大きいほど優先度が高い
• true、undefined、またはその他の数値以外の真値を返す: デフォルトの優先度 0 として扱われる

例:

datafluxRum.init({
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasQuality: 'medium',
  shouldRecordCanvas(canvas) {
    if (canvas.dataset.replay === 'off') {
      return false
    }

    if (canvas.dataset.chartRole === 'primary') {
      return 10
    }

    if (canvas.dataset.chartRole === 'secondary') {
      return 5
    }

    return 0
  }
})

これはダッシュボードで非常に役立ちます。

• メインのグラフを優先的に録画
• サブのグラフは予算がある場合に続けて録画
• 無関係な小さなグラフやサムネイルは直接除外可能

高度な上書き項目¶

デフォルトのポリシーで不十分な場合に、以下の低レベルパラメータを検討してください。

• replayCanvasMimeType エンコード形式。デフォルトは image/webp
• replayCanvasMaxCanvasSize エンコード前に許可される最大辺長。デフォルトは 1280
• replayCanvasMaxEncodedBytes 1 フレームが Replay に取り込まれることを許可される最大バイト数。デフォルトは 40000
• replayCanvasMaxConcurrentEncodes 同時エンコードの上限。デフォルトは 1
• replayCanvasFlushImmediately 正常に Replay に取り込まれた後、優先的にフラッシュするかどうか。manual のデフォルトは true、auto のデフォルトは false

以下のシナリオでのみ、これらの項目の調整を検討することを推奨します。

• ページ内の Canvas の数がデフォルトの予算を明らかに超えている場合
• 1 フレームのサイズが大きすぎるため、サイズまたはバイト数を圧縮する必要がある場合
• デバッグ結果から、現在のリズムが遅すぎる、または速すぎることが確認できた場合

Demo デバッグパネル¶

このリポジトリのローカルデモには、Canvas デバッグパネルが含まれており、現在の録画パイプラインを観察しやすくなっています。

• mode: 現在のデモで使用されている Canvas 録画モード
• auto policy: 現在のデモの初期化時に渡された interval / cooldown / unchanged backoff / failure backoff / max per run
• auto draw: デモ自身の継続的な再描画のオン/オフ。画面の変化を発生させるためだけに使用
• last trigger: 最後に手動で snapshotCanvas() を実行したトリガー元
• last snapshot: 最後に手動で snapshotCanvas() を実行した結果
• last reason: 最後の失敗理由
• auto result: 現在の設定から導き出されたポリシー結果の表示
• last event: デモ側で記録された最新のイベント状態

現在のデモは、2 つの補助機能も提供します。

• toggle auto draw: 定期的に Canvas を再描画し、auto モードで継続的に変化が発生するかを観察しやすくします
• export last canvas event: 最後に成功した手動スナップショットに対応するデバッグイベントをエクスポートします

注意が必要な点:

• auto draw はデモの動作であり、SDK 内部の自動サンプラーではありません
• auto result は現在、手動 snapshotCanvas() の結果に基づくポリシーマッピングであり、主にデバッグ説明用です
• SDK 内部の auto 定期サンプリング結果には直接接続していません
• エクスポートされるイベントも、デモ側で現在の Canvas コンテンツに基づいて再構築されたデバッグサンプルであり、intake ペイロードからの直接読み戻しではありません

パフォーマンスに関する推奨事項¶

Canvas 録画はコストの高い機能であるため、控えめに使用することを推奨します。

推奨される方法:

• 重要な瞬間にのみ snapshotCanvas() を呼び出す
• Canvas のサイズを制御する
• 優先的に replayCanvasQuality: 'low' | 'medium' | 'high' を使用する
• replayCanvasMaxConcurrentEncodes = 1 を維持する
• auto モードでは、品質プリセットにデフォルトの予算を決定させる
• ダッシュボードページでは、優先的に shouldRecordCanvas() を使用して重要なグラフのフィルタリングと優先順位付けを行う

推奨されない方法:

• 高頻度アニメーションのフレーム単位キャプチャ。WebGL は大きめの replayCanvasAutoInterval から開始し、リプレイの連続性とページパフォーマンスに応じて徐々に調整する
• 非常に大きなキャンバスに対して頻繁に呼び出す
• Canvas 録画をデフォルトのパスとして扱う

プライバシーに関する説明¶

以下の点に注意する必要があります。

• Canvas のピクセルコンテンツは、通常の DOM マスキングによる自動保護の対象外です

つまり:

• テキストノード、フォームノード、属性のサニタイズルールは、Canvas ピクセルには自動的に適用されません
• Canvas に機密情報が描画されている場合、録画後に Replay で再現される可能性があります

そのため、以下を推奨します。

• 公開リプレイが可能な Canvas に対してのみ録画を有効にする
• アカウント、電話番号、支払い情報などの機密コンテンツを含む Canvas に対して snapshotCanvas() を呼び出さない

よくある質問¶

1. snapshotCanvas() を呼び出したのに Replay で画面が表示されないのはなぜですか？¶

まず以下を確認してください。

• replayCanvasEnabled が有効になっているか
• Session Replay の録画が開始されているか
• canvas 要素を渡しているか
• Canvas の描画完了後に呼び出しているか
• サイズが大きすぎて破棄されていないか

2. 自動モードがフレーム単位で録画しないのはなぜですか？¶

現在のバージョンは自動録画をサポートしていますが、「フレーム単位の動画」ではありません。

理由:

• スナップショットサンプリングは本質的にサンプリングです
• より高再現度の自動録画は実際の描画により近くなりますが、それでも複雑なシーンの境界や自動フォールバックの制約を受けます
• Canvas のエンコードとアップロードのコストは、通常の DOM Replay よりも依然として大幅に高くなります
• WebGL はオプションのプラグインによる予算内ピクセルスナップショットを使用し、フレーム単位の録画は行いません

そのため、現在の自動モードの設計目標は次のとおりです。

• 低コストで重要な視覚状態を補完する
• 再現度とコストのバランスを取る
• Session Replay を動画録画にしない

3. WebGL の画面が表示されないのはなぜですか？¶

まず以下を確認してください。

• RUM メインパッケージが 3.3.7 以降であり、互換性のある WebGL Replay プラグインを追加でインストールまたはロードしているか。プラグインとメインパッケージは同じ SDK リリースバージョンを使用することを推奨
• webglReplayPlugin() を plugins に含めているか
• replayCanvasEnabled: true と replayCanvasMode: 'auto' の両方が有効になっているか
• プラグイン/RUM init() が WebGL エンジンのロードとコンテキスト作成より前に行われているか
• 画面が observer 起動後も実際の draw を継続して発生させているか

WebGL の最初の安全な画面は、observer 起動後の次回の実際の描画から取得されます。プラグインは、描画が終了したデフォルトのフレームバッファを非同期に読み取ることはなく、WebGL を通常の Canvas 2D スナップショットパスにフォールバックすることもありません。

4. Canvas 録画は個別にアップロードされますか？¶

いいえ。

現在のバージョンでは、Canvas スナップショットは Replay イベントの一部としてエンコードされ、通常の Replay と同じアップロードパイプラインを共有します。

5. ダッシュボードページで、一部のグラフは録画されたのに、他のグラフは録画されなかったのはなぜですか？¶

このようなページでは、通常、多数の canvas グラフが同時に存在します。「一部のグラフが録画されなかった」場合、最も一般的な原因は個々のグラフのエラーではなく、以下のとおりです。

• 自動モードでは、毎回すべてのグラフが録画されるとは限らない
• 同一画面のグラフが多すぎて、自動録画の予算が不足している
• 一部のグラフの初期描画が早すぎて、その後再描画がない
• 一部の複雑なグラフは自動高再現度モードでスナップショットにフォールバックし、コストが高くなる

優先的に以下のように対処することを推奨します。

1. ページの核心的な要求が「グラフをできるだけ漏らさない」ことである場合、以下の設定を優先的に使用します。

replayCanvasEnabled: true,
replayCanvasMode: 'auto',
replayCanvasSampling: 'all'

1. ファーストビューの重要なグラフについては、グラフのレンダリング完了後に明示的にフレームを補完します。

await datafluxRum.snapshotCanvas(canvas)

1. 重要でないグラフは引き続き自動モードに任せます。

2. shouldRecordCanvas() を使用して重要なグラフの優先度を上げるか、重要でない小さなグラフをスキップします。

shouldRecordCanvas(canvas) {
  if (canvas.dataset.miniChart === 'true') {
    return false
  }

  if (canvas.id === 'main-trend' || canvas.id === 'conversion-funnel') {
    return 10
  }

  return 1
}

安定性とコストを重視し、すべてのグラフをカバーすることは重視しない場合:

• replayCanvasSampling: 2 を維持する
• 重要なグラフに対してのみ手動で snapshotCanvas(canvas) を実行する

カバレッジを重視する場合:

• replayCanvasSampling: 'all' を試す
• さらに重要なグラフに対して手動でフレームを補完する

簡単に理解すると:

• 自動モードは「できるだけ録画する」を担当
• 手動 snapshotCanvas(canvas) は「重要なグラフを必ず録画する」を保証

サンプルシナリオ¶

直接導入に適したビジネスシナリオ:

• グラフの描画完了後に 1 回録画
• レベル終了時に 1 回録画
• ホワイトボード保存前に 1 回録画
• 署名確認後に 1 回録画

より完全な例:

function drawInvoicePreview(canvas, data) {
  const ctx = canvas.getContext('2d')
  ctx.clearRect(0, 0, canvas.width, canvas.height)
  ctx.fillStyle = '#fff'
  ctx.fillRect(0, 0, canvas.width, canvas.height)
  ctx.fillStyle = '#111827'
  ctx.font = '18px sans-serif'
  ctx.fillText('Invoice Preview', 24, 36)
  ctx.fillText('Order: ' + data.orderNo, 24, 72)
  ctx.fillText('Amount: ' + data.amount, 24, 108)
}

function refreshPreview(canvas, data) {
  drawInvoicePreview(canvas, data)
  window.DATAFLUX_RUM &&
    window.DATAFLUX_RUM.snapshotCanvas(canvas)
}

ダッシュボードシナリオの例:

datafluxRum.init({
  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasQuality: 'medium',
  shouldRecordCanvas(canvas) {
    if (canvas.dataset.miniChart === 'true') {
      return false
    }

    if (canvas.id === 'main-trend' || canvas.id === 'conversion-funnel') {
      return 10
    }

    return 1
  }
})

この設定の意味は次のとおりです。

• 小型の補助グラフはスキップ
• メインのトレンドグラフとコアファネルグラフを優先的に録画
• その他の通常のグラフは同じ優先度でラウンドロビンサンプリング

推奨事項¶

現在のバージョンでの推奨される使用方法は、一言で表すと次のとおりです。

• Canvas 録画は「重要な視覚状態のフレーム補完」として扱い、「継続的な動画録画」としては扱わない

ビジネスのタイミングが明確な場合は、優先的に manual を使用します。ダッシュボードのような複数グラフのシナリオの場合は、慎重に auto を有効にし、数値サンプリングまたは 'all' を明確に選択してください。