ブラウザ JS - ClickHouse Documentation

ClickStack ブラウザ SDK を使用すると、フロントエンドアプリケーションをインストルメントし、イベントを ClickStack に送信できます。これにより、ネットワークリクエストや例外を、バックエンドのイベントとあわせて単一のタイムラインで確認できます。さらに、セッションリプレイデータを自動的に収集して相関付けるため、アプリケーションの利用中にユーザーが見ていた内容を視覚的にたどりながらデバッグできます。このガイドでは、以下を統合します。

コンソールログ
セッションリプレイ
XHR/Fetch/WebSocket リクエスト
例外

はじめに

パッケージのインポート
スクリプトタグ

パッケージをインポートしてインストール (推奨) 以下のコマンドで、browser package をインストールします。

npm install @hyperdx/browser

ClickStack を初期化

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, // コンソールログを取得（デフォルトは false）
    advancedNetworkCapture: true, // HTTP リクエスト/レスポンスのヘッダーとボディ全体を取得（デフォルトは false）
});

スクリプトタグでインストール (代替手段) NPM でインストールする代わりに、スクリプトタグを使ってスクリプトを読み込むこともできます。これによりグローバル変数 HyperDX が利用可能になり、NPM パッケージと同じように使用できます。サイトで現在バンドラーを使用していない場合は、この方法を推奨します。

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // フロントエンドからバックエンドへのリクエストにトレースを関連付けるために設定
  });
</script>

オプション

apiKey - ClickStack のインジェスト API key。
service - イベントが HyperDX UI に表示される際のサービス名。
tracePropagationTargets - HTTP リクエストに対して照合する正規表現パターンのリストです。フロントエンドとバックエンドのトレースを関連付けるために使用され、いずれかのパターンに一致するすべてのリクエストに追加の traceparent header を追加します。これはバックエンド API のドメイン (例: api.yoursite.com) に設定してください。
consoleCapture - (任意) すべてのコンソールログを取得します (デフォルト false) 。
advancedNetworkCapture - (任意) リクエスト/レスポンスの完全なヘッダーと本文を取得します (デフォルト false) 。
url - (任意) OpenTelemetry collector の URL です。セルフホストのインスタンスでのみ必要です。
maskAllInputs - (任意) セッションリプレイですべての入力フィールドをマスクするかどうか (デフォルト false) 。
maskAllText - (任意) セッションリプレイ内のすべてのテキストをマスクするかどうか (デフォルト false) 。
disableIntercom - (任意) Intercom インテグレーションを無効にするかどうか (デフォルト false)
disableReplay - (任意) セッションリプレイを無効にするかどうか (デフォルト false)

追加の設定

ユーザー情報またはメタデータを関連付ける

ユーザー情報を関連付けると、HyperDX UI でセッションやイベントを検索・絞り込みできるようになります。これはクライアントのセッション中であれば、どの時点でも呼び出せます。この呼び出し時点のクライアントの現在のセッションと、その後に送信されるすべてのイベントがそのユーザー情報に関連付けられます。 userEmail、userName、teamName を指定すると、対応する値がセッション UI に表示されますが、これらは省略することもできます。その他の追加の値も指定でき、イベントの検索に使用できます。

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // その他のカスタムプロパティ...
});

React error boundary のエラーを自動的にキャプチャする

React を使用している場合は、error boundary コンポーネントを attachToReactErrorBoundary 関数に渡すことで、React の error boundary 内で発生したエラーを自動的にキャプチャできます。

// ErrorBoundaryをインポートします（ここではreact-error-boundaryを例として使用しています）
import { ErrorBoundary } from 'react-error-boundary';

// ErrorBoundaryコンポーネントにフックし、各インスタンス内で発生したエラーをキャプチャします。
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

カスタムアクションを送信する

特定のアプリケーションイベント (例: サインアップ、送信など) を明示的に追跡するには、イベント名と必要に応じてイベントのメタデータを指定して addAction 関数を呼び出します。例:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

ネットワークキャプチャを動的に有効にする

ネットワークキャプチャを動的に有効または無効にするには、必要に応じて enableAdvancedNetworkCapture または disableAdvancedNetworkCapture 関数を呼び出すだけです。

HyperDX.enableAdvancedNetworkCapture();

CORS リクエストのリソースタイミングを有効にする

フロントエンドアプリケーションが別ドメインに API リクエストを送信する場合は、必要に応じて Timing-Allow-Originヘッダーをリクエストとともに送信するよう有効化できます。これにより ClickStack は、DNS ルックアップやレスポンスのダウンロードなど、リクエストの詳細なリソースタイミング情報を PerformanceResourceTiming 経由で取得できるようになります。 express で cors パッケージを使用している場合は、次のスニペットを使ってこのヘッダーを有効にできます。

var cors = require('cors');
var onHeaders = require('on-headers');

// ... その他の処理

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());

​はじめに

​オプション

​追加の設定

​ユーザー情報またはメタデータを関連付ける

​React error boundary のエラーを自動的にキャプチャする

​カスタムアクションを送信する

​ネットワークキャプチャを動的に有効にする

​CORS リクエストのリソースタイミングを有効にする