Splunk RUM 用の ブラウザ RUM エージェントをインストールする 🔗
OpenTelemetry JavaScript for Web の Splunk ディストリビューションのブラウザ RUM エージェントを使用して、Web アプリケーションのフロントエンドを Splunk RUM 用にインストルメンテーションできます。
ブラウザアプリケーションをインストルメンテーションしてデータを Splunk RUM に取り込むには、このページの指示に従ってください。
互換性と必要条件をチェック 🔗
Browser RUMエージェントは、使用しているJavaScriptライブラリやフレームワークに関係なく、モダンブラウザで動作するすべてのフロントエンドエクスペリエンスを以下の要件でインストルメンテーションします:
すべてのページ、アセット、リクエストは、HTTPSプロトコルで安全に読み込まれなければなりません。
ご利用のアプリケーションは標準メソッドをオーバーライドしてはなりません。
Browser RUMエージェントは、以下のブラウザのすべてのサポート対象バージョンと互換性があります:
Google Chrome
Google Chrome for Android
Microsoft Edge
Mozilla Firefox
Apple Safari
Apple Safari for iOS
Chromiumベースのブラウザ
Microsoft Internet Explorer 11は別のレガシービルドでサポートされており、release assets on GitHubのリリースアセット で splunk-otel-web-legacy.js
として利用可能です。
注釈
Splunk RUM for Browser のインストルメンテーションに Splunk APM は必要ありません。
The Browser RUM agent runs in the following realms:
United States:
us0
,us1
,us2
Europe:
eu0
,eu1
,eu2
Asia-Pacific:
au0
,jp0
Web アプリケーションを Splunk RUM にインストルメンテーションする 🔗
Web アプリケーションに Splunk RUM をインストルメンテーションして設定する前に、RUM がアプリケーションについて収集するデータを理解し、監視する範囲を決定してください。Splunk RUM が収集したデータ を参照してください。
ウェブアプリケーションをインストルメンテーションするために、以下の方法のいずれかを選択します。
インストール方法 |
ユースケース |
考慮事項 |
---|---|---|
複数ページのウェブサイト |
サイトやアプリケーションに素早くインテグレーションできます。広告ブロッカーは読み込みを妨害する可能性があります。 |
|
複数ページのウェブサイト |
インストールをより詳細に制御できます。アップデートはすべて手動で行います。 |
|
シングルページアプリケーション |
ウェブアプリケーションにバンドルします。できるだけ早くロードする必要があります。詳しくは Load and initialize the Browser RUM agent を参照してください。 |
Splunk CDN 🔗
Splunk Content Delivery Network (CDN) を使用して、ブラウザ RUM エージェントを同期的にロードできます。CDN リンクにより、アプリケーションは常に最新バージョンを使用できるようになります。
使用環境で実行するバージョンを決める 🔗
ブラウザ RUM エージェントのバージョニングは、意味的なバージョニングルールに従っています。ロードするバージョンをよりコントロールするには、以下のバージョン管理ポリシーを参照してください:
最新バージョンを使用してブラウザ RUMエージェントの最新バージョンを使用します。プリプロダクションでは、
latest
を使用して最新バージョンの Splunk RUM を試してください。事前のテストなしに本番環境で使用しないでください。このバージョンは、メジャーバージョン変更の間に API の変更が発生する可能性があるため、手動でのインストルメンテーションには適していない可能性があります。APIとの後方互換性を保ちつつ、新機能を自動的に受け取りたい場合は、メジャーバージョン、例えば
v1
を使用してください。これは、npmのインストールと同様に、すべてのプロダクションデプロイメントのデフォルトです。マイナーバージョン、例えば
v1.1
を使用すると、バグフィックスを受け取ることができますが、一方で、新機能を自動的に受け取りません。例えば、
v1.2.1
のように、パッチバージョンを使用して、アプリケーションの特定のバージョンのエージェントを固定します。
エージェントのバージョンは、指定されたトークンとして URL に含まれます。例:
https://cdn.signalfx.com/o11y-gdi-rum/v<MAJOR.MINOR.PATCH>/splunk-otel-web.js
本番環境では、事前に本番環境でテストした固定バージョンを使用し、毎月のサイクルで本番バージョンを更新します。
CDNスクリプトをアプリケーションに追加する 🔗
以下の手順に従って、CDNを使用してアプリケーションをインストルメンテーションしてください:
次のスニペットをカスタマイズします:
<!--// IMPORTANT: Replace the <version> placeholder in the src URL with a version from https://github.com/signalfx/splunk-otel-js-web/releases //--> <script src="https://cdn.signalfx.com/o11y-gdi-rum/<version>/splunk-otel-web.js" crossorigin="anonymous"></script> <script> SplunkRum.init({ realm: '<realm>', rumAccessToken: '<your_rum_token>', applicationName: '<your_app_name>', version: '<your_app_version>', deploymentEnvironment: '<your_environment_name>' }); </script>
スクリプトのURLで、
<version>
を GitHub のReleases ページに あるバージョンに置き換えます。realm
は Splunk Observability Cloud レルムで、例えばus0
です。Splunk レルムを見つけるには、レルムに関する注意 を参照してください。RUM アクセストークンを生成するには、Generate your RUM access token in Splunk Observability Cloud を参照してください。
このスニペットを、アプリケーションで監視したいすべてのページのheadセクションに追加します。
変更をアプリケーションにデプロイします。本番環境にデプロイする前に、必ず事前に本番環境でインストルメンテーションをテストしてください。
注意
事前のテストなしに latest
バージョンを本番で使用しないでください。
セルフホストスクリプト 🔗
独自のCDNを使用したり、独自のデプロイメント要件に準拠したりするには、セルフホストスクリプトを使用してアプリケーションをインストルメンテーションします。スクリプトをホストする場合、エージェントの新しいバージョンに手動で更新する必要があります。
以下の手順に従って、セルフホストスクリプトを使用してアプリケーションをインストルメンテーションします:
GitHub の splunk-otel-js-web にアクセスして、使いたいリリースの
splunk-otel-web.js
ファイルをダウンロードしてください。アプリケーションのユーザーがアクセスできる場所にファイルをデプロイします。
次のスニペットをカスタマイズします:
<script src="http://example.domain/path/splunk-otel-web.js"></script> <script> SplunkRum.init({ realm: '<realm>', rumAccessToken: '<your_rum_token>', applicationName: '<your_app_name>', version: '<your_app_version>', deploymentEnvironment: '<your_environment_name>' }); </script>
realm
は Splunk Observability Cloud のレルムで、例えばus0
。エンドポイントのレルム を参照してください。RUM アクセストークンを生成するには、Generate your RUM access token in Splunk Observability Cloud を参照してください。
このスニペットを、アプリケーションで監視したいすべてのページのheadセクションに追加します。
変更をアプリケーションにデプロイします。本番環境にデプロイする前に、必ず事前に本番環境でインストルメンテーションをテストしてください。
npmパッケージ 🔗
ブラウザ RUMエージェントをアプリケーションに直接バンドルするには、@splunk/otel-web
npmパッケージを使用します。
以下の手順に従って、npm を使用して Splunk RUM をインストルメンテーションおよび設定します:
以下のコマンドを入力して、ブラウザ RUMエージェントをインストールし、package.jsonファイルに追加します:
npm install @splunk/otel-web --save
バンドルルートファイルの隣に
splunk-instrumentation.js
初期化ファイルを作成します。次のスニペットは初期化ファイルのサンプルです:import SplunkOtelWeb from '@splunk/otel-web'; SplunkOtelWeb.init({ realm: '<realm>', rumAccessToken: '<your_rum_token>', applicationName: '<your_application_name>', version: '<your_app_version>', deploymentEnvironment: '<your_environment_name>' });
realm
は Splunk Observability Cloud のレルムで、たとえばus0
です。アカウントのレルム名を確認するには、以下の手順に従ってください:Splunk Observability Cloud のナビゲーションメニューを開きます。
を選択します。
ユーザー名を選択します。
レルム名は Organizations セクションに表示されます。
RUM アクセストークンを生成するには、Generate your RUM access token in Splunk Observability Cloud を参照してください。
インストルメンテーションがアプリケーションコードより先に実行されるように、
splunk-instrumentation.js
ファイルを他のファイルより先にインポートするか、要求してください。変更をアプリケーションにデプロイします。本番環境にデプロイする前に、必ず事前に本番環境でインストルメンテーションをテストしてください。
注釈
Splunk RUM エージェントが Node.js で実行されていないことを確認してください。Splunk APM で Node.js サービスをインストルメンテーションするには、Splunk Observability Cloud に Node.js アプリケーションをインストルメンテーションする を参照してください。
Load and initialize the Browser RUM agent 🔗
データの欠落を避けるため、ブラウザ RUMエージェントは、同期してできるだけ早い段階でロードし、初期化してください。ロードが遅れると、インストルメンテーションが初期化される前にデータを収集できないため、データが欠落する可能性があります。
ブラウザ RUMエージェントのロードと初期化には、効果的な順に以下の方法のいずれかを使用します:
ブラウザ RUMエージェントを、ヘッドセクションの最初のリソース、または少なくとも最初のJSリソースとして同期ロードします。ブラウザ RUMエージェントのJavaScriptファイルは、他のどのJSファイルよりも先にロードされなければなりません。これにより、インストルメンテーションがすべてのユーザーインタラクション、リソース、エラーを収集することが保証されます。
ブラウザ RUM エージェントを他のアプリケーションスクリプトとバンドルします。ブラウザ RUMエージェントをバンドルの先頭に配置し、バンドルが同期してロードされることを確認します。
ブラウザ RUMエージェントのロードを延期する場合は、初期化の順序を維持するために、他のスクリプトも延期されていることを確認してください。非同期にロードされたスクリプトはサポートされていないことに注意してください。
セッション再生をセットアップする 🔗
セッション再生を使用すると、セッションを再生してユーザーが経験したことを正確に把握し、次に何をすべきかを十分な情報を得た上で決定することができます。
セッション再生のセットアップと設定方法については、Splunk RUM でのセッション再生 を参照してください。
RUMデータ取り込みのカスタマイズ 🔗
ブラウザ RUMエージェントのデータ取り込みをカスタマイズして、ノイズを減らし、情報を再編集することができます。
error.messageコレクションのオプトアウト 🔗
error.message
レスポンスの収集を避けるには、以下の例のように、エラー・インストルメンテーションを無効にします:
<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
SplunkRum.init({
realm: '<realm>',
rumAccessToken: '<your_rum_token>',
applicationName: '<your_app_name>',
version: '<your_app_version>',
instrumentations: { errors: false }
});
</script>
収集前に属性を変更する 🔗
スパンの属性を削除または変更するには、個人を特定できる情報(PII)のサニタイズ を参照してください。
シングルページアプリケーションのフレームワークでエラーを収集する 🔗
シングルページアプリケーションフレームワークを使用する際のエラー収集については、シングルページアプリケーションのフレームワークでエラーを収集する を参照してください。
RUM と Splunk APM をリンクする 🔗
Splunk RUM は、サーバータイミングを使用してアプリケーションのフロントエンドとバックエンド間の応答時間を計算し、フロントエンドとバックエンドのトレースを結合してエンドツーエンドを可視化します。
デフォルトでは、OpenTelemetry の Splunk ディストリビューションはすでに Server-Timing
ヘッダーを送信しています。このヘッダーはブラウザからのスパンとバックエンドのスパンおよびトレースをリンクします。
注釈
Safari ブラウザを使用して Splunk RUM から Splunk APM にセッションをリンクする場合、Safari は Splunk APM への XHR およびフェッチリクエストのリンクをサポートしていますが、Splunk APM へのページロードまたはリソースロードのリンクはサポートしていないことに注意してください。
モバイルアプリケーションでWebViewをインストルメンテーションする 🔗
モバイルインストルメンテーションとウェブインストルメンテーションの間で`splunk.rumSessionId` を共有することで、iOS および Android アプリケーションの WebView をインストルメンテーションできます。これにより、ネイティブアプリとウェブアプリの両方のデータを単一のストリームで見ることができます。
WebViewをインストルメンテーションするには、アプリのオペレーティングシステムの指示に従ってください:
コンテンツ・セキュリティ・ポリシーに関する考慮事項 🔗
クロスサイトスクリプティング (XSS) やその他の攻撃による潜在的な影響を軽減するために、アプリケーションでコンテンツ・セキュリティ・ポリシー (CSP) を使用している場合は、そのポリシーで Splunk RUM の実行が許可されていることを確認してください:
エージェントのCDNバージョンを使用する場合、
script-src cdn.signalfx.com
URLを許可します。セルフホストまたはnpmパッケージを使用する場合は、それに応じてサイトを設定してください。
Add the host from the
beaconEndpoint
property to theconnect-src
property. For example:connect-src rum-ingest.us1.signalfx.com
.
貢献する方法 🔗
Splunk Distribution of OpenTelemetry JavaScript for Web はオープンソースソフトウェアです。GitHub でプルリクエストを作成することで、その改善に貢献することができます。詳しくは、GitHub の 貢献ガイドライン を参照してください。