セッションリプレイ

ClickStack でユーザーセッションを記録・再生し、フロントエンドの問題をデバッグして、ユーザー行動を把握し、ブラウザのアクティビティをバックエンドのログやトレースと相関付けます。

ClickStack のセッションリプレイは、Web アプリケーション内でのユーザー操作を記録・再構成し、セッション中にユーザーが実際に見て何をしたのかを、そのまま視覚的に再生できるようにします。動画を録画するのではなく、SDK は DOM の変更、マウスの動き、クリック、スクロール、キーボード入力、コンソールログ、ネットワークリクエスト (XHR、Fetch、WebSocket) 、JavaScript の例外を記録し、その体験をブラウザ内で再構成します。

セッションリプレイは、ログ、トレース、メトリクスとともに ClickHouse に保存されるため、ユーザー体験を確認してから、それを支えたバックエンドのトレースやデータベースクエリの調査まで、すべて数回のクリックで行えます。これにより、セッションリプレイは本番環境の問題のデバッグ、ユーザー行動の把握、UX 上のつまずきポイントの特定、さらにサポートに報告された問題の視覚的な確認に役立ちます。

​

アプリケーションをインストルメントする

ClickStack は OpenTelemetry と完全に互換性があるため、標準の OpenTelemetry JavaScript SDK または任意の ClickStack language SDKs を使用して、ブラウザのテレメトリー (トレース、例外) を送信できます。ただし、セッションリプレイには ClickStack Browser SDK (@hyperdx/browser) が必要です。これは、セッション記録、コンソールキャプチャ、ネットワークリクエストのキャプチャ機能を OpenTelemetry SDK に拡張したものです。セッションリプレイが不要でトレースだけが必要な場合は、OTel 互換の任意のブラウザ SDK を ClickStack で利用できます。

以下の例では ClickStack Browser SDK を使用します。アプリケーションにセッションリプレイを追加するには、パッケージをインストールし、SDK を初期化するだけで完了します。あとは、すべてのユーザー操作が自動的にキャプチャされるため、追加のコード変更は不要です。

SDK は、アプリの起動時に確実に読み込まれる場所で初期化してください。たとえば Next.js アプリケーションであれば、ルートの layout.js が該当します。これによりセッション記録がすぐに開始され、ユーザー体験全体をキャプチャできます。

NPM

npm install @hyperdx/browser

import HyperDX from '@hyperdx/browser';

HyperDX.init({
  url: 'http://your-otel-collector:4318',
  apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
  service: 'my-frontend-app',
  tracePropagationTargets: [/api.myapp.domain/i],
  consoleCapture: true,
  advancedNetworkCapture: true,
});

Yarn

yarn add @hyperdx/browser

import HyperDX from '@hyperdx/browser';

HyperDX.init({
  url: 'http://your-otel-collector:4318',
  apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
  service: 'my-frontend-app',
  tracePropagationTargets: [/api.myapp.domain/i],
  consoleCapture: true,
  advancedNetworkCapture: true,
});

スクリプトタグ

バンドラを使用しないアプリケーションでは、スクリプトタグで SDK を直接読み込んでください。これによりグローバル変数 HyperDX が公開され、NPM パッケージと同じように使用できます。

<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i],
    consoleCapture: true,
    advancedNetworkCapture: true,
  });
</script>

tracePropagationTargets オプションは、セッションリプレイをバックエンドのトレースと関連付けるうえで重要です。これを API ドメインに設定すると、フロントエンドからバックエンドまでの完全な分散トレーシングを有効にできます。プライバシー制御、custom actions、React エラーバウンダリ、ソースマップなどを含む SDK オプションの一覧については、Browser SDK reference を参照してください。

Browser SDK は、プライバシーに配慮が必要なアプリケーション向けに 入力内容やテキストのマスキング もサポートしており、さらに ユーザー情報を付加する ことで、ClickStack UI でユーザーごとにセッションを検索およびフィルタリングできます。

​

セッションリプレイの表示

ClickStack UI (HyperDX) の左側のサイドバーから Client Sessions に移動します。このビューには、キャプチャされたすべてのブラウザーセッションが、継続時間とイベント数とともに一覧表示されます。

任意のセッションの再生ボタンをクリックすると、そのセッションをリプレイできます。リプレイ画面では、右側に再現されたユーザー体験が表示され、左側にはブラウザーイベント (ネットワークリクエスト、コンソールログ、エラー) のタイムラインが表示されます。

タイムラインに表示する詳細度は、Highlighted モードと All Events モードを切り替えて調整できます。エラーは赤色で示され、任意のイベントをクリックすると、リプレイはそのセッション内の該当時点に移動します。

​

セッションからトレースへ

セッションタイムラインでネットワークリクエストやエラーを選択すると、Trace タブをクリックして、そのリクエストがバックエンドサービス内をどのように流れたかを追跡できます。そこでは、そのユーザー操作によってトリガーされた関連ログ、スパン、データベースクエリを確認できます。

これは、tracePropagationTargets 設定が traceparent ヘッダーを介してブラウザのスパンとサーバーのスパンを関連付け、ユーザーのクリックからデータベースに至るまで一貫した分散トレースを構築するためです。フロントエンドとバックエンドの両方をインストルメントする方法を含め、実際の手順を詳しく知りたい場合は、Instrumenting your NextJS application with OpenTelemetry and ClickStackを参照してください。

​

トレースからセッションへ

この相関は逆方向にも機能します。Search ビューでトレースを表示している際にそのトレースをクリックして詳細を開き、Session replay タブを選択すると、そのトレース発生時にユーザーが実際にどのような操作をしていたかを確認できます。これは、エラーやリクエスト遅延を調査する際に特に有用です。バックエンド側の問題から調査を始めて、すぐにユーザー視点の状況を確認できます。

​

セッションデータの保存方法

セッションリプレイのデータは、ログやトレースとは別に、ClickHouse 内の専用の hyperdx_sessions テーブルに保存されます。各セッションイベントは 1 行として保存され、イベントのペイロードを含む Body フィールドと、イベントのメタデータを格納する LogAttributes マップを持ちます。Body と LogAttributes の両カラムには、リプレイの再構築に使用される実際のセッションイベントの詳細が格納されます。

テーブルスキーマの詳細については、ClickStack で使用されるテーブルとスキーマ を参照してください。

​

試してみる

セッションリプレイを実際に確認する方法は 2 つあります。

• ライブデモ — clickpy.clickhouse.com にアクセスしてアプリを操作し、その後 play-clickstack.clickhouse.com の ClickPy Sessions ログソースで自分のセッションリプレイを確認します。ClickPy をどのようにインストルメントしたかの詳細については、ブログ記事 Instrumenting your NextJS application with OpenTelemetry and ClickStack を参照してください。
• ローカルデモ — Session replay demo では、ClickStack をローカルで実行し、リプレイを表示するところまで含めて、デモアプリケーションを段階的にインストルメントする手順を説明しています。

​

さらに詳しく

• Session replay demo — ステップごとの手順を備えた、対話型のローカルデモアプリケーション
• Browser SDK Reference — SDK の全オプション、source maps、custom actions、高度な設定
• Search — セッションやイベントを絞り込むための検索構文
• Dashboards — セッションデータやトレースデータから可視化やダッシュボードを作成
• Alerts — エラー、レイテンシ、その他のシグナルに対するアラートを設定
• ClickStack Architecture — ClickHouse、HyperDX、OTel collector がどのように連携するか