セッションリプレイのデモ

TL;DR

このガイドでは、ClickStack Browser SDK を使用してセッションリプレイ用に Web アプリケーションに計測（インストルメンテーション）を行う手順を説明します。他の事前生成データを読み込むサンプルデータセットとは異なり、このデモでは、実際の操作を通じてセッションデータを生成できるインタラクティブなアプリケーションを提供します。

所要時間：10〜15分

概要

session replay デモアプリケーションは、vanilla JavaScript で構築されたドキュメント閲覧用アプリケーションです。セッションリプレイのインストルメンテーションをどれほど最小限に抑えられるかを示しており、1 つの script タグと 1 回の初期化呼び出しだけで、すべてのユーザー操作を自動的に取得できます。

このリポジトリには 2 つのブランチが含まれています:

main — すべてインストルメンテーション済みで、すぐに利用可能なブランチ
pre-instrumented — インストルメンテーションのないクリーンなバージョンで、どこに追加すべきかを示すコードコメント付きのブランチ

このガイドでは、まず main ブランチを使ってセッションリプレイの動作を確認し、その後インストルメンテーションコードを順に解説し、同じパターンを自分のアプリケーションに適用できるようにします。

セッションリプレイの概要と、それが ClickStack にどのように組み込まれているかについては、Session Replay 機能ページを参照してください。

前提条件

Docker および Docker Compose がインストールされていること
ポート 3000、4317、4318、8080 が利用可能であること

デモを実行する

リポジトリをクローンする

git clone https://github.com/ClickHouse/clickstack-session-replay-demo
cd clickstack-session-replay-demo

ClickStack を起動する

docker-compose up -d clickstack

API キーを取得する

http://localhost:8080 で HyperDX を開きます
必要に応じてアカウントを作成するかログインします
Team Settings → API Keys に移動します
インジェスト API key をコピーします

環境変数として設定します:

export CLICKSTACK_API_KEY='your-api-key-here'

デモアプリケーションを起動する

docker-compose --profile demo up demo-app

注記

CLICKSTACK_API_KEY 変数をエクスポートしたのと同じターミナルでこのコマンドを実行してください。

ブラウザで http://localhost:3000 を開き、アプリを操作します。トピックを検索したり、カテゴリでフィルタしたり、コード例を表示したり、項目をブックマークしたりしてみてください。

すべての操作は ClickStack Browser SDK によって自動的に収集されます。

セッションリプレイを表示する

http://localhost:8080 の HyperDX に戻り、左側のサイドバーから Client Sessions に移動します。

セッションが一覧表示され、各セッションの継続時間とイベント数が確認できるはずです。▶️ ボタンをクリックしてリプレイします。

Highlighted モードと All Events モードを切り替えて、タイムラインに表示される詳細度を調整します。

インストルメンテーション

このデモアプリケーションは、セッションリプレイを有効化するために必要なコードがいかに少なくて済むかを示しています。アプリケーション側で行う追加は、次の 2 点だけです。

1. SDK を組み込む（app/public/index.html）：

<script src="https://unpkg.com/@hyperdx/[email protected]/build/index.js"></script>

2. ClickStack の初期化 (app/public/js/app.js):

window.HyperDX.init({
  url: 'http://localhost:4318',
  apiKey: window.CLICKSTACK_API_KEY,
  service: 'clickhouse-session-replay-demo',
  consoleCapture: true,
  advancedNetworkCapture: true,
});

それ以外の部分はすべて標準的なアプリケーションコードです。SDK がユーザー操作、コンソールログ、ネットワークリクエスト、エラーを自動的にすべて収集するため、追加の計装は不要です。

自分で試してみる

アプリにゼロからインスツルメンテーションを行うには、pre-instrumented ブランチに切り替えてください。

git checkout pre-instrumented

このブランチには、ClickStack のインストルメンテーションが一切含まれていない同じアプリケーションが含まれています。app/public/index.html と app/public/js/app.js のコードコメントに、上記 2 つのコードスニペットをどこに追加するかが正確に示されています。追加したら、デモアプリを再起動してください。以降、行った操作が ClickStack 上に表示され始めます。

トラブルシューティング

HyperDX にセッションが表示されない

ブラウザのコンソールにエラーが出力されていないか確認します
ClickStack が起動していることを確認します: docker-compose ps
API キーが設定されていることを確認します: echo $CLICKSTACK_API_KEY
Client Sessions ビューで時間範囲を調整します（Last 15 minutes を選択してみてください）
ブラウザをハードリロードします: Cmd+Shift+R (Mac) または Ctrl+Shift+R (Windows/Linux)

401 Unauthorized エラー

API キーが正しく設定されていません。次の点を確認してください。

ターミナルで環境変数としてエクスポートしていること: export CLICKSTACK_API_KEY='your-key'
そのキーをエクスポートした同じターミナルでデモアプリを起動していること
HyperDX UI から取得したキーを使っていること（ランダムに生成された文字列ではないこと）

クリーンアップ

サービスを停止します：

docker-compose down

全データの削除:

docker-compose down -v

詳細情報

Session Replay — 機能概要、SDK オプション、およびプライバシー制御機能
Browser SDK Reference — SDK オプションの一覧と詳細な設定方法
ClickStack Getting Started — ClickStack をデプロイして、最初のデータを取り込む手順
All Sample Datasets — その他のサンプルデータセットとガイド

概要​

前提条件​

デモを実行する​

リポジトリをクローンする​

ClickStack を起動する​

API キーを取得する​

デモアプリケーションを起動する​

セッションリプレイを表示する​

インストルメンテーション​

自分で試してみる​

トラブルシューティング​

HyperDX にセッションが表示されない​

401 Unauthorized エラー​

クリーンアップ​

詳細情報​

概要