Web アプリケーションの導入¶
本ページの設定を完了すると、Browser RUM SDK はページ View、リソースリクエスト、フロントエンドエラー、ユーザー操作を自動収集し、データを Guance に送信します。
App 内の WebView ページについては、先に WebView ページの導入 を読み、ページのユースケースに応じて初期化方法を選択してください。
初回導入では、まずコンソールで「アプリを定義 → 導入方法を選択 → 導入設定」を完了し、その後データ送信を検証してください。基本データの送信に成功したら、必要に応じてサンプリング、分散型トレーシング、セッションリプレイを調整できます。
アプリを定義¶
- 「RUM > アプリ一覧」に移動し、「アプリを作成」をクリックして、アプリケーションタイプで「Web」を選択します。
- 「アプリを定義」でアプリケーション名とアプリケーション ID を入力します。アプリケーション作成後、クライアントデータ送信用の Client Token が自動生成されます。
- 「導入方法を選択」で次の表のいずれかの方法を選択し、「導入設定」に従って対応する操作を完了します。
既存のアプリケーションがある場合は、その設定ページに直接移動し、アプリケーション情報を確認してから導入を続行できます。
導入方法を選択¶
| 導入方法 | ユースケース | 操作入口 |
|---|---|---|
| Agent 自動導入 | コーディングアシスタントにプロジェクトを分析させ、SDK 導入を完了したい場合 | コンソールで生成されたプロンプトをコピーし、アプリケーションのコードリポジトリでコーディングアシスタントに実行させる |
| 手動導入 | 業務コードを自身で変更し、SDK の読み込み方法を選択してパラメータを設定したい場合 | 先にデータ送信方法を選択し、アプリケーション形態に応じて SDK を導入する |
| サーバー自動導入 | Nginx または IIS で Web サイトをホストし、サーバー経由で SDK を注入したい場合 | コンソールで収集パラメータを設定し、対象サーバーで導入コマンドを実行する |
同一ページでは 1 つの導入方法を選択してください。すでに RUM SDK があるページでは、重複初期化や重複収集を避けるため、まず既存の設定を確認する必要があります。
Agent 自動導入¶
- アプリケーション設定ページで「Agent 自動導入」を選択します。
- 「導入設定」にある完全なプロンプトをコピーします。これには現在のアプリケーション ID、DataWay アドレス、一時認可コードなどの導入情報が含まれます。
- アプリケーションのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付けます。Agent は導入ガイドに従ってプロジェクト構造を分析し、既存の設定を再利用して、必要な SDK 導入と検証を完了します。
- 導入の検証に従って、実際のデータ送信と取り込み状況を確認します。
プロンプトの導入ガイドには、実行環境と具体的な手順が記載されています。導入情報が未準備の場合は、次のように処理します:
- 個人用 API キーが未生成:「API キーを生成する」をクリックし、完了後にプロンプトをコピーし直します。必要な権限がない場合は、ワークスペース管理者に連絡して開通してください。
- 一時認可コードが未準備:先に Agent にプロジェクトを分析させ、必要な情報を補った後に導入を続行できます。
手動導入¶
手動導入は 2 つのステップに分かれます。まずデータ送信方法を選択し、次に NPM や CDN などの SDK 読み込み方法を選択します。
| データ送信方法 | 推奨ユースケース | 初期化パラメータ |
|---|---|---|
| パブリック DataWay を使用 | 通常はこれを優先。Guance がデータ受信サービスを提供 | applicationId、site、clientToken |
| ローカル環境デプロイ | DataKit を自身でデプロイおよび管理する必要がある場合、または現在のワークスペースでパブリック DataWay アドレスが提供されていない場合 | applicationId、datakitOrigin |
2 つの送信方法のうち 1 つだけを選択してください。site と clientToken はパブリック DataWay 用、datakitOrigin はローカル環境デプロイ用です。同じ初期化設定に同時に記述しないでください。
送信設定を準備¶
- 「手動導入」で「パブリック DataWay を使用」を選択します。
- 現在のアプリケーションの導入設定から
applicationId、site、clientTokenをコピーします。コンソールが提供する現在のサイトアドレスを使用し、コンソールのログインアドレスや他のサイトのアドレスをsiteにしないでください。 - SDK を導入する際に次の設定を保持します。DataKit のインストールや RUM コレクターの別途設定は不要です。
- DataKit をインストールし、RUM コレクターを有効にします。
- ユーザーのブラウザがあるネットワークから DataKit のデータ送信先アドレスにアクセスできることを確認し、必要に応じて IP 地理情報データベースをインストールして、ユーザー IP に対応する地理情報を解決します。
- 「手動導入」で「ローカル環境デプロイ」を選択し、
datakitOriginを実際の DataKit 受信アドレスに設定します。HTTPS ページでは、ブラウザにリクエストがブロックされないよう、アクセス可能な HTTPS 受信アドレスを使用してください。 - SDK を導入する際に
siteとclientTokenを削除し、次の設定に切り替えます。
サーバー自動導入¶
Nginx または IIS を介して Web サイトの HTML ページに RUM SDK を注入します。アプリケーションコードの変更は不要ですが、対象サーバーの設定権限とコマンド実行権限が必要です。
前提条件¶
- Web アプリケーションが作成済みで、対象サーバーの設定権限とコマンド実行権限があること。
- ページに注入可能な
<head>タグが含まれていること。同一ページでは RUM SDK の導入方法を 1 つだけ保持し、重複収集を避けてください。 - ブラウザから SDK リソースとデータ送信先アドレスにアクセスできること。CSP を使用する場合は、CSP セキュリティポリシーに従って許可範囲を設定してください。
| サーバー | 環境要件と操作への影響 |
|---|---|
| Nginx | Linux Nginx 1.9.4+、http_sub_module、Bash、curl。root または sudo で実行します。導入設定の変更により Nginx がリロードされます |
| IIS | 64 ビット Windows、IIS 7.5+、URL Rewrite 2.x、静的リソースの読み取り権限、専用アプリケーションプール。管理者として PowerShell 5.1+ を実行します。有効化、停止、更新、ロールバックによりアプリケーションプールがリサイクルされ、プロセス内セッションが失われる可能性があります |
導入を設定¶
- Web アプリケーション設定ページの「導入方法を選択」で「サーバー自動導入」を選択します。
- 「アプリケーションを接続」で OpenWay または DataKit を選択し、送信先アドレス、サービス名、環境、アプリケーションバージョンを確認します。アプリケーションバージョンはビジネスバージョンをマークするために使用され、SDK をアップグレードするものではありません。
- 「SDK の取得元と読み込み」でリソースの取得元と読み込み方法を確認します。
- 「収集内容」でセッションサンプリングレート、エラーセッション補償サンプリングレート、ユーザーインタラクション収集を設定します。必要に応じてセッションリプレイを有効にし、リプレイサンプリングレート、エラーリプレイ補償サンプリングレート、プライバシーレベルを設定します。リプレイはまずセッションサンプリングを経て、その後リプレイサンプリングを経ます。
- 「インストール環境」で Nginx または IIS を選択し、現在の環境要件を確認します。必要に応じて「高度な導入設定」を展開します。
- 「インストールコマンドを実行」で現在の設定から生成されたコマンドをコピーし、対象サーバーで実行します。サイトの自動検出を使用する場合は、ターミナルのプロンプトに従って導入するサイトを選択します。
コマンドには設定が含まれているため、ファイルを個別にダウンロードする必要はありません。記録保存や手動更新が必要な場合は、rumable.toml をダウンロードできます。コマンドと設定には Client Token が含まれるため、適切に保管してください。
検証と更新¶
コマンド実行後、まずサーバーの実行結果を確認し、次に導入の検証に従って、Web サイト内の SDK が正常に動作し、データが取り込まれていることを確認します。インストールに成功しただけ、またはページが HTTP 200 を返しただけでは、データ収集が成功したことを証明できません。
データが受信されない場合は、有効化されたサイトとパスにアクセスしているか、SDK が CSP によってブロックされていないか、送信先アドレスに到達可能か、セッションがサンプリングされているかを確認します。ページで既に NPM または CDN 経由で SDK を導入している場合は、先に重複導入を解消してください。
収集パラメータを変更した後は、導入コマンドを再生成し、対象サーバーで実行してください。コンソールで設定を保存またはコピーするだけでは、サーバー上のインジェクション設定は自動更新されません。ダウンロードした rumable.toml を変更した場合も、サーバーで再適用する必要があります。
SDK パラメータの意味はパラメータ設定を参照し、サンプリングルールはサンプリング設定を参照してください。
SDK の手動導入¶
次の例では、デフォルトでパブリック DataWay を使用します。ローカル環境デプロイを使用する場合は、送信設定を準備に従って送信パラメータを置き換えてください。
アプリケーション形態に応じて、次の表の導入入口を選択してください。NPM と CDN はページで SDK を読み込む方法を決定し、パブリック DataWay とローカル DataKit はデータの送信先を決定します。両者は個別に設定します。
| アプリケーション形態 | 推奨入口 | 説明 |
|---|---|---|
| Webpack、Vite、Rollup などのビルドツールを使用 | NPM 導入 | 推奨方法。バージョン管理と必要な機能のみの導入が容易。初期化前のリクエストやエラーを取り逃す可能性がある |
| フロントエンドのビルドプロセスがない | CDN 非同期読み込み | ページ解析をブロックしないが、初期化前のリクエストやエラーを取り逃す可能性がある |
| ページのエラーとリクエストをできるだけ早く収集する必要がある | CDN 同期読み込み | できるだけ早く初期化するが、ページ読み込み時間を消費する |
| 基本的な RUM のみが必要で、フロントエンドのバンドルサイズを重視 | スリム版 RUM SDK | 通常の RUM 収集を維持し、Session Replay と送信圧縮は含まない |
| React、Vue、Angular のシングルページアプリケーション | フロントエンドフレームワークプラグインの導入 | Router View とフレームワークエラーを自動管理 |
| Next.js、Nuxt | SSR フレームワークでの導入 | サーバー側とブラウザ環境を区別し、View の重複を避ける |
| Electron | Electron アプリケーションの導入 | renderer process でのみ初期化 |
| App 内の WebView ページ | WebView ページの導入 | 通常の統合と App 内埋め込み専用のシナリオを区別し、ホスト側では各プラットフォームに応じて Bridge を設定 |
NPM 導入¶
フロントエンドプロジェクトで SDK をインストールして読み込みます:
プロジェクトで SDK を初期化します:
import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-app",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
trackUserInteractions: true
})
CDN 同期読み込み¶
HTML ファイルにスクリプトを追加します:
<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: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-app",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
trackUserInteractions: true
})
</script>
CDN 非同期読み込み¶
HTML ファイルにスクリプトを追加します:
<script>
;(function (h, o, u, n, d) {
h = h[d] = h[d] || {
q: [],
onReady: function (c) {
h.q.push(c)
},
}
d = o.createElement(u)
d.async = 1
d.src = n
n = o.getElementsByTagName(u)[0]
n.parentNode.insertBefore(d, n)
})(
window,
document,
"script",
"https://static.guance.com/browser-sdk/v3/dataflux-rum.js",
"DATAFLUX_RUM"
)
DATAFLUX_RUM.onReady(function () {
DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-app",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
trackUserInteractions: true
})
})
</script>
DOM のみを記録するセッションリプレイ¶
Browser SDK 3.3.25 以降、DOM リプレイ用スクリプトを読み込むと、RUM イベントの収集と DOM の記録ができます。
Canvas 2D または WebGL を記録するページにはフル版を使用してください。各ページに読み込むバンドルは 1 つです。初期化 API とリプレイのサンプリング設定は共通です。
スリム版 RUM SDK¶
RUM SDK 3.3.3 以降ではスリム版を提供します。スリム版はフル版と同じ初期化方法を使用し、View、Resource、Long Task、Error、Action、ユーザーとグローバル Context、カスタムイベント、分散型トレーシングなどの通常の RUM 機能をサポートします。ページ録画が不要で、フロントエンドのバンドルサイズを削減したいアプリケーションに適しています。
NPM 導入¶
通常の RUM パッケージを同じバージョンのスリム版パッケージに置き換えます:
import { datafluxRum } from "@cloudcare/browser-rum-slim"
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-app",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
trackUserInteractions: true
})
CDN 導入¶
同期または非同期の読み込み方法はフル版と同じで、スクリプトファイル名をスリム版に対応するファイルに置き換えるだけです。以下は同期読み込みの例です:
<script
src="https://static.guance.com/browser-sdk/v3/dataflux-rum-slim.js"
type="text/javascript"
></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
service: "web-app",
env: "production",
version: "1.0.0",
sessionSampleRate: 100,
trackUserInteractions: true
})
</script>
フル版との機能差異¶
スリム版には次の機能は含まれません:
- Session Replay、および
startSessionReplayRecording()、stopSessionReplayRecording()、isRecording()などの録画 API; - Canvas 2D、WebGL/WebGL2 の録画、および
snapshotCanvas()などの Canvas API; compressIntakeRequestsによる送信圧縮と対応する Worker。
スリム版では、sessionReplaySampleRate、sessionReplayOnErrorSampleRate、replayCanvasEnabled を強制的に無効に設定し、compressIntakeRequests を強制的に false に設定します。導入時にこれらの設定を渡さないでください。workerUrl や replayCanvasWorkerUrl を設定する必要もありません。後でセッションリプレイ、Canvas 録画、圧縮送信が必要になった場合は、NPM パッケージまたは CDN ファイルをフル版に戻してください。その他の基本的な初期化パラメータは引き続き使用できます。
導入の検証¶
次の手順は Web SDK の単独送信用です。App WebView Bridge モードの場合は、WebView データの検証を直接参照してください。
- SDK を導入したページを開き、ページ遷移、ボタンクリック、API リクエストを一度ずつ実行します。
- ブラウザの開発者ツールの Network で
/v1/write/rumをフィルターし、成功した送信リクエストが存在することを確認します。 - Console を確認し、
Application ID is not configuredやdatakitOrigin or site is not configuredなどの初期化エラーがないことを確認します。 - 「RUM > アプリ一覧」に移動し、対象の Web アプリケーションを開き、エクスプローラーで導入設定の
service、env、versionで絞り込み、View、Resource、Action データを受信済みであることを確認します。
View データが表示されれば、基本的な導入は成功です
Error、Resource、Action は、ページで実際に対応するイベントが発生した後にのみ表示されます。データがない場合は、まず現在の Session が sessionSampleRate のサンプリング対象になっているか確認し、その後 FAQ を参照してください。
SDK 初期化結果の取得¶
Web RUM のフル版とスリム版では、Browser SDK 3.3.25 以降で初期化コールバックをサポートします。
既存の init() 呼び出しに onInitSuccess と onInitError を指定します。CDN から非同期で読み込む場合は、onReady() 内で init() を呼び出します。
SDK は設定の検証と必要なセッションストレージの確認を終えてから onInitSuccess を呼び出します。remoteConfiguration が有効な場合は、先にリモート設定を処理します。フル版で圧縮送信を使用する場合、成功コールバックは圧縮 Worker の準備が整うまで待ちます。View の自動収集はコールバックより先に始まることがあります。スリム版と JSON 形式で送信するフル版では、圧縮 Worker を待つ必要はありません。
次の例はパブリック DataWay を使用しています。initOptions を現在の RUM インスタンスの init(initOptions) に渡すだけです。
const initOptions = {
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
remoteConfiguration: true,
onInitSuccess(result) {
console.log("RUM 初始化成功", result.remoteConfiguration)
if (result.remoteConfiguration === "fallback") {
console.warn("RUM 已使用本地配置启动", result.remoteConfigurationError.code)
}
},
onInitError(error) {
console.error("RUM 初始化失败", error.code, error.message)
}
}
result.remoteConfiguration |
意味 |
|---|---|
disabled |
リモート設定が無効になっており、SDK はローカル設定を使用して初期化を完了します。 |
applied |
SDK は有効なリモート応答を処理済みです。空の設定が返された場合でも、ローカル設定は引き続き有効です。 |
fallback |
リモートリクエストまたは応答の解析に失敗し、SDK はローカル設定を使用して初期化を完了します。remoteConfigurationError には code と message が含まれ、HTTP エラーの場合は status も含まれます。 |
リモートリクエストのタイムアウトは 10 秒です。タイムアウト、ネットワークエラー、200 以外の応答、または応答形式のエラーが発生すると、ローカル設定へのフォールバックがトリガーされます。ローカル設定でも SDK を起動できない場合、今回の呼び出しでは onInitError のみがトリガーされます。
1 回の init() 呼び出しでトリガーされる結果コールバックは最大 1 つです。init() は undefined を返し、コールバックは init() が返る前に同期的に実行される場合があります。View を手動で管理する場合は、onInitSuccess 内で startView() を呼び出して最初の View を作成できます。Web SDK が単独で送信する場合は、導入の検証に従ってブラウザの送信リクエストを確認し、対象の Web アプリケーションで View を確認してください。App WebView Bridge を使用する場合は App SDK がデータを送信するため、WebView データの検証に従って対象の App アプリケーションで View を確認してください。
error.code |
対処方法 |
|---|---|
invalid_configuration、invalid_plugins |
ローカルまたはリモートで上書きされた後のパラメータとプラグイン設定を確認し、修正後に init() を再度呼び出します。 |
storage_unavailable |
ブラウザの cookie、localStorage、セッションストレージの設定を確認し、ストレージを復旧してから再試行します。 |
worker_initialization_failed |
フル版で圧縮 Worker の起動に失敗したか、タイムアウトしました。SDK は onInitError を 1 回呼び出します。error.message の内容に応じて、Worker の URL(workerUrl)、ネットワーク接続、コンテンツセキュリティポリシー(CSP)を確認してください。修正後にページを再読み込みして初期化します。現在のページで再度 init() を呼び出しても無視されます。 |
already_initialized |
この呼び出しは拒否され、最初の呼び出しが自身のコールバックを保持します。silentMultipleInit はコンソールの通知のみを制御します。 |
initialization_ignored |
現在のインスタンスは初期化を Synthetics が注入したインスタンスに委ねます。 |
sdk_disabled、initialization_failed |
SDK の構築または起動時に例外が発生しました。原因を調査して修正し、ページを更新してください。 |
よく使うオプション設定¶
基本データの確認に成功したら、必要に応じて他の機能を有効にします:
| 目標 | 設定または API | ドキュメント |
|---|---|---|
| フロントエンドとバックエンドのトレースを関連付け | allowedTracingUrls、traceType |
分散型トレーシング設定 |
| 匿名訪問者ごとに API リクエスト頻度を制限 | visitorId、resetVisitorId() |
訪問者識別子 Visitor ID |
| 収集比率を制御 | sessionSampleRate、startSession() |
サンプリング設定 |
| エラーセッションのイベントのみを収集 | sessionOnErrorSampleRate |
エラーセッション補償サンプリング |
| セッションリプレイを有効化 | startSessionReplayRecording() |
Web セッションリプレイ |
| 送信データを圧縮 | compressIntakeRequests |
データ圧縮 |
| SPA Router View を自動管理 | plugins |
フロントエンドフレームワークプラグインの導入 |
| WebGL/WebGL2 を録画 | plugins、Canvas 自動録画 |
Canvas 録画使用マニュアル |
| ログインユーザーを識別 | setUser() |
カスタムユーザー識別子 |
| ビジネスフィールドまたはイベントを追加 | Global Context、addAction()、addError() |
カスタムデータとイベント |
分散型トレーシング設定(任意)¶
NPM + TypeScript で導入する場合、traceType には対応ブランドの browser-core パッケージからインポートした TraceType 列挙型を使用する必要があります:
import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/browser-rum"
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
allowedTracingUrls: ["https://api.example.com"],
traceType: TraceType.DDTRACE
})
TraceType.DDTRACE の実行時の値は引き続き "ddtrace" です。CDN 導入ではモジュールのインポートがないため、明示的に設定する場合は対応する実行時文字列を使用します。分散型トレーシングを有効化した後は、API サーバー側で対応する Trace Header を許可する必要もあります。詳細は APM と RUM の関連付け方法を参照してください。
通常の Session がサンプリング対象にならない場合でも、Trace Header をバックエンドに渡す必要がある場合は、allowTraceHeaderWithoutSession を明示的に有効化できます:
datafluxRum.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
sessionSampleRate: 0,
sessionOnErrorSampleRate: 0,
allowedTracingUrls: ["https://api.example.com"],
allowTraceHeaderWithoutSession: true
})
有効化後も、SDK は allowedTracingUrls に一致する XHR および Fetch リクエストにのみ Trace Header を注入します。この設定は RUM Session を作成または強制的に有効化せず、未サンプリング Session の View、Error、Resource、Action データも送信しません。API サービスでは引き続き、選択した traceType に対応するリクエストヘッダーを許可する必要があります。クロスオリジンリクエストでは、CORS も正しく設定する必要があります。
パラメータ設定¶
初期化パラメータ¶
| パラメータ | 型 |
必須 |
デフォルト値 |
説明 |
|---|---|---|---|---|
applicationId |
String | はい | Guance で作成したアプリケーション ID。 | |
datakitOrigin |
String | ローカル環境デプロイ時 | DataKit のデータ送信先アドレス。形式は プロトコル(:// を含む)+ ドメインまたは IP + 任意のポート です(例:https://datakit.example.com)。 |
|
clientToken |
String | パブリック DataWay 時 | パブリック DataWay のデータ送信 Token。Guance コンソールから取得します。 | |
site |
String | パブリック DataWay 時 | パブリック DataWay のデータ送信先アドレス。Guance コンソールから取得します。 | |
env |
String | いいえ | Web アプリケーションの現在の環境(例:prod:本番環境、gray:グレー環境、pre:プレリリース環境、common:日常環境、local:ローカル環境)。 | |
version |
String | いいえ | Web アプリケーションのバージョン番号。 | |
service |
String | いいえ | 現在のアプリケーションのサービス名。デフォルトは browser で、カスタム設定をサポートします。 |
|
sessionSampleRate |
Number | いいえ | 100 |
メトリクスデータの収集割合:100 は全収集、0 は収集なしを意味します。 |
sessionOnErrorSampleRate |
Number | いいえ | 0 |
エラーセッション補償サンプリングレート:セッションが sessionSampleRate でサンプリングされていない場合に、セッション中にエラーが発生すると、この割合で収集します。このようなセッションはエラー発生時点からイベントを記録し、セッション終了まで記録を続けます。SDK バージョン要件 >= 3.2.19 |
sessionReplaySampleRate |
Number | いいえ | 100 |
Session Replay データ収集割合:100 は全収集、0 は収集なしを意味します。 |
sessionReplayOnErrorSampleRate |
Number | いいえ | 0 |
Session Replay エラーセッションリプレイ補償サンプリングレート:セッションが sessionReplaySampleRate でサンプリングされていない場合に、セッション中にエラーが発生すると、この割合で収集します。このようなリプレイはエラー発生直前の最大 1 分間のイベントを記録し、セッション終了まで記録を続けます。SDK バージョン要件 >= 3.2.19 |
trackSessionAcrossSubdomains |
Boolean | いいえ | false |
同じドメイン下のサブドメイン間でキャッシュを共有します。 |
usePartitionedCrossSiteSessionCookie |
Boolean | いいえ | false |
パーティション化された安全なクロスサイトセッション cookie を有効にするかどうか 詳細 |
useSecureSessionCookie |
Boolean | いいえ | false |
安全なセッション cookie を使用します。これにより、安全でない(HTTPS 以外の)接続で送信される RUM イベントが無効になります |
traceType |
TraceType |
いいえ | TraceType.DDTRACE(実行時の値は ddtrace) |
分散型トレーシングツールのタイプを設定します。NPM 導入では TraceType 列挙型を使用し、CDN 導入では対応する実行時文字列を使用します。現在、DDTRACE(ddtrace)、ZIPKIN_MULTI_HEADER(zipkin)、ZIPKIN_SINGLE_HEADER(zipkin_single_header)、W3C_TRACEPARENT(w3c_traceparent)、W3C_TRACEPARENT_64(w3c_traceparent_64bit)、SKYWALKING_V3(skywalking_v3)、JAEGER(jaeger)をサポートしています。❗️ 1. OpenTelemetry は zipkin_single_header、w3c_traceparent、zipkin、jaeger の 4 種類をサポートします。2. この設定の有効化は allowedTracingUrls に依存します。3. 対応するタイプを設定する場合、API サービスに適切な Access-Control-Allow-Headers を設定する必要があります。詳細はAPM と RUM の関連付け方法を参照してください。 |
traceId128Bit |
Boolean | いいえ | false |
traceID を 128 ビットモードで生成するかどうか。traceType に対応し、現在 zipkin、jaeger をサポートしています。 |
allowedTracingUrls |
Array | いいえ | [] |
Trace Header を注入できるリクエスト URL のマッチリスト。配列要素には完全な URL、正規表現、マッチ関数、または match と traceType を含むオブジェクトを指定できます。例:["https://api.example.com/xxx", /https:\/\/.*\.my-api-domain\.com\/xxx/, (url) => url.includes("/api/")]。 |
allowTraceHeaderWithoutSession |
Boolean | いいえ | false |
現在の RUM Session がサンプリング対象にならない場合でも、allowedTracingUrls に一致する XHR および Fetch リクエストに Trace Header を注入するかどうか。有効化しても Session は作成されず、未サンプリング Session の RUM データも送信されません。 |
allowedTracingOrigins |
Array | いいえ | [] |
非推奨。旧バージョンの設定との互換性のためにのみ保持されています。新規導入では allowedTracingUrls を使用してください。両方を設定した場合、allowedTracingUrls がこの設定を上書きします。 |
trackUserInteractions |
Boolean | いいえ | false |
ユーザー行動の収集を有効にするかどうか。 |
enablePrivacyForActionName |
Boolean | いいえ | false |
自動 Action 名を DOM プライバシーレベルに従わせるかどうか。有効化すると、マスクされた名前は固定プレースホルダーを使用し、非表示要素内のクリックでは自動 Action が生成されません。明示的に設定された Action 名属性は引き続き使用できます。SDK バージョン要件 >= 3.3.14。詳細は自動 Action 名の保護を参照してください。 |
trackViewsManually |
Boolean | いいえ | false |
SDK の自動 View を無効にし、アプリケーションが startView() を呼び出して手動で View を開始するかどうか。フレームワーク Router プラグインはこの設定を自動管理するため、業務側で重複して設定する必要はありません。詳細参照 |
plugins |
Array | いいえ | [] |
RUM プラグインを登録します。init() 時に渡す必要があります。フレームワークプラグインは React、Vue、Angular、Next.js、Nuxt のルート View とフレームワークエラーを収集できます。SDK バージョン要件 >= 3.3.6。詳細はフロントエンドフレームワークプラグインの導入を参照してください。WebGL Replay は SDK 3.3.7 以降で提供され、RUM メインパッケージのバージョン >= 3.3.7 が必要です。プラグインとメインパッケージには同じ SDK リリースバージョンを使用することを推奨します。詳細はCanvas 録画使用マニュアルを参照してください。 |
enableExperimentalFeatures |
Array | いいえ | [] |
実験的機能を有効化します。["track_websockets"] を設定すると、ネイティブ WebSocket の接続レベルの Resource を収集できます。SDK バージョン要件 >= 3.3.6。詳細参照 |
actionNameAttribute |
String | いいえ | バージョン要件:>3.1.2。要素にカスタム属性を追加して操作名を指定します。具体的な使用方法は詳細を参照してください。 |
|
beforeSend |
Function(event, context):Boolean | いいえ | バージョン要件:>3.1.2。データのインターセプトおよびデータの変更。詳細参照 |
|
storeContextsToLocal |
Boolean | いいえ | バージョン要件:>3.1.2。ユーザーカスタムデータをローカル localstorage にキャッシュするかどうか(例:setUser、addGlobalContext API で追加したカスタムデータ)。 |
|
storeContextsKey |
String | いいえ | バージョン要件:>3.1.18。localstorage に保存する key を定義します。デフォルトでは未入力で、自動生成されます。このパラメータは主に、同じドメイン下で異なるサブパスが store を共有する問題を区別するためのものです。ユーザー識別子とセッション境界の設定についてはページ更新とローカルストレージを参照してください。 |
|
compressIntakeRequests |
Boolean | いいえ | RUM データリクエストの内容を圧縮し、大量データ送信時の帯域幅使用量を削減すると同時に、送信データのリクエスト数も削減します。圧縮は WebWorker スレッドで行われます。CSP セキュリティポリシーについては CSP セキュリティを参照してください。SDK バージョン要件 >= 3.2.0。datakit バージョン要件 >=1.60。デプロイメントプランでは >= 1.96.178 が必要です |
|
workerUrl |
String | いいえ | sessionReplay と compressIntakeRequests のデータ圧縮はいずれも webwork スレッドで行われるため、デフォルトでは CSP セキュリティアクセスを有効にする場合、worker-src blob:; を許可する必要があります。この設定では、セルフホストの worker アドレスを追加できます。CSP セキュリティポリシーについては CSP セキュリティを参照してください。SDK バージョン要件 >= 3.2.0。 |
|
remoteConfiguration |
Boolean | いいえ | データ収集のリモート設定機能を有効にするかどうか。デフォルトでは無効です。リモート設定機能では、新バージョンをリリースせずにデータ収集の設定項目を動的に変更できます。たとえば、リモート設定でサンプリングレートやユーザー行動収集の有効/無効を変更できます。リモート設定機能を利用するには、Guance コンソールで環境変数設定を有効にする必要があります。SDK バージョン要件 >= 3.2.20。datakit バージョン要件 >=1.60。Guanceコンソールで環境変数機能を有効にする方法 |
|
onInitSuccess |
function |
いいえ | SDK 3.3.25 以降でサポート。初期化成功時に呼び出され、引数にはリモート設定の処理結果が含まれます。詳細は初期化結果を参照してください。 |
|
onInitError |
function |
いいえ | SDK 3.3.25 以降でサポート。今回の初期化失敗または呼び出し拒否時にトリガーされ、引数には code と message が含まれます。詳細はエラーコードを参照してください。 |
|
replayCanvasWorkerUrl |
string |
いいえ | canvas snapshot のエンコード専用 worker アドレス。workerUrl の代替ではありません。この設定では、セルフホストの worker アドレスを追加できます。CSP セキュリティポリシーについては CSP セキュリティを参照してください。SDK バージョン要件 >= 3.3.0。 |
|
replayCanvasEnabled |
boolean |
いいえ | false |
canvas 録画を有効にするかどうか。有効にしない場合、canvas は収集されません。SDK バージョン要件 >= 3.3.0。 |
replayCanvasMode |
'manual' \| 'auto' |
いいえ | auto |
canvas 録画モード。manual では snapshotCanvas(canvas) を手動で呼び出す必要があります。auto は自動録画です。 |
replayCanvasSampling |
number \| 'all' |
いいえ | 2 |
replayCanvasMode: 'auto' の場合にのみ有効です。正の数値は自動 snapshot パスを選択し、2 から開始することを推奨します。数値自体は Canvas 2D の収集頻度を制御しません。'all' を指定すると、Canvas 2D はより高い再現度の command capture を試みますが、複雑なシーンでは snapshot にフォールバックする場合があります。WebGL プラグインは常に予算付きのピクセルスナップショットを使用します。 |
replayCanvasAutoInterval |
number |
いいえ | 250 |
各 Canvas の自動 snapshot 目標間隔(ミリ秒)。複数 Canvas は公平にローテーションされ、実際の周期は cooldown、backoff、ページ可視性、グローバル実行時予算によって制限されます。 |
replayCanvasQuality |
'low' \| 'medium' \| 'high' \| number |
いいえ | 0.4 |
Canvas snapshot のエンコード品質。文字列プリセットは sampling と自動スケジューリング予算も同時に調整します。画像品質のみを変更したい場合は、0 から 1 の間の数値を渡してください。 |
replayCanvasAutoCooldown |
number |
いいえ | 250 |
同じ Canvas の自動 snapshot の最小クールダウン時間(ミリ秒)。 |
replayCanvasAutoUnchangedBackoff |
number |
いいえ | 3000 |
軽量シグネチャが継続的に変化しない場合に、次の完全なエンコード検証をトリガーする間隔(ミリ秒)。その間も、有界で適応的なリズムで変化を検出します。 |
replayCanvasAutoFailureBackoff |
number |
いいえ | 5000 |
自動収集失敗後のバックオフ時間(ミリ秒)。 |
replayCanvasAutoMaxPerRun |
number |
いいえ | 2 |
1 回の自動スケジューリングで処理する Canvas の最大数。 |
replayCanvasFlushImmediately |
boolean |
いいえ | manual: trueauto: false |
Canvas フレームが replay に正常に入った後、優先的に flush するかどうか。 |
silentMultipleInit |
boolean |
いいえ | 重複初期化のコンソール通知を無効にするかどうか。設定済みの onInitError では引き続き already_initialized を受信します。 |
low、medium、high の文字列プリセットを使用しない場合、Canvas 自動スケジューリングのベースラインは次のとおりです:sampling 2、各 Canvas の目標 interval 250 ms、cooldown 250 ms、unchanged backoff 3000 ms、failure backoff 5000 ms、1 回の実行で最大 2 個の Canvas。文字列プリセットはこれらの予算とエンコード品質を同時に置き換えます。複数 Canvas は公平なローテーションとグローバル収集予算の制限も受けます。明示的な個別設定はプリセットの対応する値を上書きします。完全なプリセットマトリクスはCanvas 録画使用マニュアルを参照してください。
上記の高頻度スケジューリングベースラインは Canvas 2D 用です。WebGL プラグインで interval/cooldown を明示的に設定しない場合は、より保守的な GPU 読み戻し周期を引き続き採用します。明示的な個別設定によってのみ、それぞれ上書きされます。
パブリック DataWay サイトアドレス¶
site はパブリックデータ受信アドレスを指定するために使用します。現在のアプリケーションの導入設定にあるアドレスを優先してコピーしてください。次の表はサイトの確認用です。ローカル環境デプロイの場合は、datakitOrigin を設定するだけで済みます。
| ノード名 | アドレス |
|---|---|
| 中国リージョン 1(杭州) | https://rum-openway.guance.com |
| 中国リージョン 2(寧夏) | https://aws-openway.guance.com |
| 中国リージョン 4(広州) | https://cn4-openway.guance.com |
| 中国リージョン 6(香港) | https://cn6-openway.guance.one |
| 国際リージョン 1(オレゴン) | https://us1-openway.guance.com |
| ヨーロッパリージョン 1(フランクフルト) | https://eu1-openway.guance.one |
| アジアパシフィックリージョン 1(シンガポール) | https://ap1-openway.guance.one |
| アジアパシフィックリージョン 2(シンガポール) | https://ap2-openway.guance.com |
| アフリカリージョン 1(南アフリカ) | https://za1-openway.guance.com |
| インドネシアリージョン 1(ジャカルタ) | https://id1-openway.guance.com |
実行時 Session 制御¶
RUM SDK 3.3.6 で startSession() が追加されました。呼び出すと現在の Session を即座に終了し、現在のサンプリング設定に従って Session を再開します。次のユーザーインタラクションを待つ必要はありません:
実行時の sessionSampleRate を同時に上書きすることもできます:
サンプリングレートは 0 から 100 の間である必要があります。この上書き値は今回および後続で自動継続される Session に使用されます。フル RUM パッケージとスリム RUM パッケージの両方でこの API をサポートしています。詳細なセマンティクスとユースケースについては実行時に Session を再開するを参照してください。
必要に応じて高度な機能を有効化¶
エラーセッションのイベントのみを収集¶
バージョン要件
SDK バージョン要件 >= 3.2.19。
sessionOnErrorSampleRate は、通常のサンプリングに一致しないエラーセッションを補償します。セッションでエラーが発生し、補償サンプリングに一致した場合、SDK はエラー発生時点からイベントを記録し、セッション終了まで続けます。
次の例では、通常のセッションサンプリングを無効にし、エラーセッション補償サンプリングレートを 100% に設定します。
設定プラン¶
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
sessionSampleRate: 0,
sessionOnErrorSampleRate: 100
})
上記の例はパブリック DataWay を使用しています。ローカル環境デプロイの場合は、基本的な導入例に従って送信先アドレスのフィールドを置き換えてください。
データ圧縮¶
ページに大量の静的リソース(JS、CSS、画像など)が含まれる場合、またはサンプリングレートが高い場合、多数の RUM 送信データが生成される可能性があります。
compressIntakeRequests: true を設定すると、SDK は Web Worker で deflate を使用して送信データを圧縮し、リクエストサイズとリクエスト数を削減します。
設定例¶
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
compressIntakeRequests: true
})
注意事項¶
- データ圧縮ロジックは Web Worker で実行されます。CSP セキュリティポリシーを有効にしている場合は、
worker-srcでblob:を許可する必要があります。詳細は CSP セキュリティポリシーの説明を参照してください。 - SDK は
workerUrl設定項目でセルフホストの Worker アドレスを指定できます。 - この機能を使用する SDK バージョンは >= 3.2 である必要があります。
カスタムデータとイベント¶
ビジネス目標に応じて対応する API を選択し、CDN、NPM の導入例とパラメータ説明を確認してください:
- ユーザー操作の追跡:クリックの自動収集、Action 名の定義、カスタム Action の追加。
- カスタムユーザー識別子:ログイン後にユーザーを設定し、ログアウトまたはアカウント切替時にユーザーをクリアします。
- グローバルコンテキスト:後続のすべての RUM イベントに安定したビジネスディメンションを追加します。
- カスタム Action の追加:ページクリックでは表現できないビジネス操作を記録します。
- カスタム Error の送信:すでに捕捉された例外、またはビジネス側で能動的に識別した例外を送信します。
Web セッションリプレイ¶
前提条件
Session Replay を含むフル RUM パッケージを使用してください。スリム RUM パッケージにはセッションリプレイ機能は含まれません。
録画を有効化¶
SDK 初期化後に、startSessionReplayRecording() メソッドを呼び出してセッションリプレイの録画を有効にします。ユーザーログイン後など、特定の条件下で セッション録画を有効化することもできます。
エラーに関連するセッションリプレイデータのみを収集¶
バージョン要件
SDK バージョン要件 >= 3.2.19。
sessionReplayOnErrorSampleRate は、通常のリプレイサンプリングに一致しないエラーセッションを補償します。セッションでエラーが発生し、補償サンプリングに一致した場合、エラー発生直前の最大 1 分間のリプレイデータを遡って取得でき、セッション終了まで記録を続けます。
次の例では、すべての RUM セッションを収集し、通常のリプレイサンプリングを無効にし、エラーセッションリプレイ補償サンプリングレートを 100% に設定して、録画 API を呼び出します。セッションリプレイは引き続き RUM セッションのサンプリング結果に制約されます。具体的なルールはサンプリング設定を参照してください。
設定例¶
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
applicationId: "<APPLICATION_ID>",
site: "<PUBLIC_DATAWAY_URL>",
clientToken: "<CLIENT_TOKEN>",
sessionSampleRate: 100,
sessionReplaySampleRate: 0,
sessionReplayOnErrorSampleRate: 100
})
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
注意事項¶
- セッションリプレイは iframe、動画、音声の再生内容を記録しません。Canvas はデフォルトでは収集されず、
replayCanvasEnabledを個別に設定する必要があります。WebGL/WebGL2 は SDK3.3.7以降で提供され、RUM メインパッケージのバージョン>= 3.3.7が必要です。さらに互換性のあるbrowser-rum-webglプラグインをインストールして登録する必要があります。プラグインとメインパッケージには同じ SDK リリースバージョンを使用することを推奨します。詳細はCanvas 録画使用マニュアルを参照してください。 - リプレイ時に静的リソース(フォント、画像など)へ正常にアクセスできるようにするため、CORS ポリシーを設定する必要がある場合があります。
- CSS スタイルとマウスホバーイベントをサポートするため、CSSStyleSheet インターフェース経由で CSS ルールにアクセスできることを確認してください。
録画状態の検証¶
window.DATAFLUX_RUM.isRecording() を呼び出して現在のページが録画中かどうかを確認し、セッションリプレイエクスプローラーで対応する Session にリプレイデータが生成されていることを確認します。本番環境では、その後ビジネス要件に応じて sessionReplaySampleRate を調整してください。