メインコンテンツへスキップ
要点このガイドでは、HyperDX Chrome拡張機能を使用して、任意のWebサイトに ClickStack Browser SDK を注入する方法を説明します。対象アプリケーションのソースコードを変更する必要はありません。拡張機能を一度設定すれば、あとはサイトを閲覧するだけで、ClickStack でセッションリプレイを確認できます。所要時間: 10〜15分

​
概要

HyperDX Chrome拡張機能 は、アクセスしたページに @hyperdx/browser SDK を挿入します。コードベースを変更せずに、サイト上でセッションリプレイ、RUM、またはトレース伝播をデバッグしたい場合に便利です。たとえば、サードパーティ製アプリケーション、本番ビルド、または厳格な Content Security Policy (CSP) が設定されたローカル開発サーバーなどで役立ちます。 SDK は拡張機能内にバンドルされているため (約480 KB) 、ページ側で実行時に CDN からスクリプトを読み込む必要はありません。この拡張機能はまず外部の chrome-extension:// スクリプト挿入を試み、CSP によって拡張機能由来のスクリプトがブロックされた場合は、インライン挿入にフォールバックします。 制御可能なデモアプリケーションをインストルメントする Session Replay Demo とは異なり、この方法は Chrome で開いた 任意の URL で機能します。通常のユーザーとしてサイトを操作することで、セッションデータを生成できます。 セッションリプレイの背景や、ClickStack における位置づけについては、Session Replay 機能ページを参照してください。

​
前提条件

  • Google Chrome または Chromium ベースのブラウザー (Edge、Brave など)
  • ClickStack をローカルで実行する場合は、Docker がインストールされていること
  • ポート 4317、4318、8080 が使用可能であること (ローカルの ClickStack 用)

​
デモを実行する

1

​
拡張機能のリポジトリをクローンする

2

​
拡張機能をインストールする

  1. Chrome を開き、chrome://extensions にアクセスします。
  2. デベロッパー モード を有効にします (右上) 。
  3. パッケージ化されていない拡張機能を読み込む をクリックします。
  4. クローンした hyperdx-chrome-extension ディレクトリを選択します。
拡張機能はツールバーに HyperDX Browser Extension として表示されます。
3

​
ClickStack を起動する

すでに ClickStack または HyperDX のインジェスト エンドポイントがある場合は、拡張機能を設定する に進んでください。ローカルの ClickStack 環境では、OpenTelemetry Collector を起動します。{{CLICKHOUSE_ENDPOINT}} と {{CLICKHOUSE_PASSWORD}} は ClickHouse の接続情報に置き換えてください。
UI が起動していることを確認するには、http://localhost:8080 で HyperDX を開きます。ClickHouse と HyperDX UI を含む完全なローカルデプロイについては、ClickStack を使い始める を参照してください。
4

​
API key を取得する

ローカルの ClickStack では、API key が不要な場合があります。http://localhost:4318 上のセルフホスト collector にテレメトリーを送信する場合は、拡張機能のこのフィールドを空のままにしてください。ClickStack Cloud または HyperDX Cloud へインジェストする場合は、HyperDX を開いて Team Settings → API Keys に移動し、Ingestion API Key をコピーします。
5

​
拡張機能を設定する

Chrome のツールバーにある HyperDX Browser Extension アイコンをクリックし、各設定を入力します。Save Configuration をクリックし、インストルメントしたいタブを再読み込みします。上のスクリーンショットは、典型的なローカル設定を示しています。監視が有効で、サービス名が設定され、collector は http://localhost:4318 を指し、トレース伝播は API と localhost の URL に限定されています。
6

​
サイトを閲覧してセッションを生成する

Chrome で任意の Web サイトまたはローカルアプリケーションを開きます。たとえば、フロントエンドの開発サーバーなら http://localhost:3000 です。通常どおりにページを操作します。リンクをクリックし、フォームを送信し、エラーをトリガーし、ビュー間を移動します。設定が正しければ、拡張機能はページの読み込みごとに Browser SDK を自動的にインジェクトします。
7

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

http://localhost:8080 の HyperDX に戻り、左側のサイドバーから Client Sessions に移動します。セッションが継続時間とイベント数とともに一覧表示されるはずです。▶️ ボタンをクリックしてリプレイします。タイムラインの詳細レベルを調整するには、Highlighted モードと All Events モードを切り替えます。

​
URL フィルタリング

デフォルトでは、監視が有効になっている間、拡張機能はアクセスしたすべてのページに SDK を挿入します。挿入先を特定のサイトのみに制限するには、一致する URL にのみ挿入 を有効にし、パターンを 1 行に 1 つずつ (またはカンマ区切りで) 追加します。 URL パターンを保存したら、タブを再読み込みしてください。

​
挿入を確認する

監視対象のページで DevTools を開き (Console タブ) 、ページを再読み込みして、以下を確認します。
拡張機能からのスクリプトがCSPによってブロックされた場合、拡張機能はフォールバックメッセージをログに出力し、インラインでの挿入に切り替えて再試行します。

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

  1. ブラウザーのコンソールで [HyperDX Extension] のログメッセージやエラーを確認します
  2. Enable HyperDX Monitoring がオンになっていて、Service Name が設定されていることを確認します
  3. ClickStack が実行中で、collector の URL が正しいことを確認します (例: http://localhost:4318)
  4. Client Sessions ビューで時間範囲を調整します (Last 15 minutes を試してください)
  5. ブラウザーを強制再読み込みします: Cmd+Shift+R (Mac) または Ctrl+Shift+R (Windows/Linux)
chrome://extensions で拡張機能を再読み込みしてから、タブを強制再読み込みします。これは、タブを開いたまま拡張機能が更新または再読み込みされた場合に発生します。
  1. 監視が有効になっていて、サービス名が設定されていることを確認します
  2. Only inject on matching URLs がオンの場合は、現在のページ URL がいずれかのパターンに一致していることを確認します
  3. 一部のサイトでは、CSP によって拡張機能由来のスクリプトとインラインスクリプトの両方の挿入がブロックされるため、そのページではインジェクトできない場合があります
API key フィールドが空の場合は想定どおりの動作です。Cloud エンドポイントを使う場合は HyperDX で発行したインジェスト API key を追加してください。セルフホストの collector が認証なしのローカルトラフィックを受け入れる場合は、無視して構いません。

​
プライバシー

この拡張機能は、アクセスしたページにオブザーバビリティ用のコードを挿入します。使用するのは、デバッグが許可されているサイトに限ってください。APIキーを共有したり、バージョン管理システムにコミットしたりしないでください。

​
詳細はこちら

最終更新日 2026年7月2日