Splunk ブラウザ RUM インストルメンテーションを設定する 🔗

OpenTelemetry JS for Web の Splunk ディストリビューションからブラウザ RUM エージェントを設定することで、カスタム属性の追加、環境やアプリケーションに合わせたインストルメンテーション、サンプリングのカスタマイズなどを行うことができます。

設定方法 🔗

ブラウザRUMエージェントを設定するには、SplunkRum.init() 関数に渡されるオブジェクトを編集します：

<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
      SplunkRum.init(
      {
         realm: 'us0',
         rumAccessToken: 'ABC123...789',
         applicationName: 'my-awesome-app',
         version: '1.0.1'
         // Any additional settings
      });
</script>

一般設定 🔗

以下の設定を使用して、ブラウザRUMエージェントを構成します：

プロパティ	タイプ	説明
`realm`	文字列	組織のレルム名、例えば `us0` 。アカウントのレルム名を確認するには、Splunk Observability Cloud のナビゲーションメニューを開き、Settings を選択し、ユーザー名を選択します。レルム名は Organizations セクションに表示されます。
`rumAccessToken`	文字列（必須）	エージェントがテレメトリデータを Splunk Observability Cloud に送信することを許可する RUM トークン。RUM アクセストークンを生成するには、Generate your RUM access token in Splunk Observability Cloud を参照してください。
`beaconEndpoint`	文字列（ `realm` が設定されていない場合は必須）	エージェントが収集したテレメトリを送信するインジェスト URL。 `realm` が設定されている場合、URL は `https://rum-ingest.<realm>.signalfx.com/v1/rum` の形式になります。エンドポイントを手動で設定する場合、これは `realm` の値を上書きします。
`applicationName`	文字列	アプリケーションの名前。デフォルト値は `unknown-browser-app` です。
`version`	文字列	全スパンのアプリケーションのバージョン。例えば、」1.0.1 「または「20220820」。
`deploymentEnvironment`	文字列	アプリケーションによって生成されるすべてのスパンの環境。例えば、`dev` 、`test` 、または `prod` 。
`globalAttributes`	オブジェクト	すべてのスパンに追加される属性を設定します。例えば、`version` または `user_id` 。
`instrumentations`	オブジェクト	特定のブラウザRUMインストルメンテーションをアクティブまたは非アクティブにします。インストルメンテーション設定を参照してください。
`ignoreUrls`	`(string\\|regex)[]`	エージェントが無視しなければならないURLのリスト。一致するURLはスパンを生成しません。文字列または正規表現の2種類のルールを指定できます。
`cookieDomain`	文字列	セッショントラッキングに使用されるドメイン。たとえば、`foo.example.com` と `bar.example.com` の両方にサイトがある場合、`cookieDomain` を `example.com` に設定すると、両方のサイトで同じセッション識別子を使用できます。詳しくは、ブラウザRUMエージェントが使用するクッキーを参照してください。
`context.async`	ブーリアン	非同期コンテキストマネージャーを有効にします。デフォルト値は `true` です。非同期トレース設定を参照してください。
`exporter.onAttributesSerializing`	`(a: SpanAttributes, s?: Span) => SpanAttributes`	エクスポート前にspan属性を修正するためのコールバックを提供します。デフォルト値は `(attrs) => attrs` です。サンプルシナリオは個人を特定できる情報（PII）のサニタイズです。
`tracer`	オブジェクト	`WebTracerProvider` に渡されるトレース設定。サンプリングの設定に使用できます。サンプリング設定を参照してください。
`debug`	ブーリアン	開発者コンソールのデバッグロギングを有効にします。デフォルト値は `false` です。

インストルメンテーション設定 🔗

特定のブラウザRUMインストルメンテーションをアクティブまたは非アクティブにするには、オブジェクトを構成し、instrumentations プロパティに渡します。以下のエージェント初期化の例は、いくつかのインストルメンテーションの設定を変更します：

SplunkRum.init(
   {
      beaconEndpoint: 'https://rum-ingest.us0.signalfx.com/v1/rum',
      rumAccessToken: 'ABC123…789',
      applicationName: 'my-awesome-app',
      instrumentations:
      {
         interactions:
         {
            // Adds``gamepadconneted`` events to the
            // list of events collected by default
           eventNames: [
             ...SplunkRum.DEFAULT_AUTO_INSTRUMENTED_EVENT_NAMES,
             'gamepadconnected'
           ],
         },
         longtask: false, // Deactivates monitoring for longtasks
         websocket: true, // Activates monitoring for websockets
      },
   });

instrumentations オプションで対応しているすべてのプロパティを以下の表に示します：

プロパティ	デフォルト	説明
`connectivity`	`false`	接続イベントの収集をアクティブにします。接続性を参照してください。
`document`	`true`	ドキュメント読み込みイベントに関連するスパンの収集をアクティブにします。ドキュメントのロードを参照してください。
`errors`	`true`	JavaScript エラーの収集をアクティブにします。ブラウザRUMエージェントが収集したエラーを参照してください。
`fetch`	`true`	Fetch API リクエストの収集をアクティブにします。XHRとFetchインストルメンテーションを参照してください。
`interactions`	`true`	クリックやキーの押下などのユーザーインタラクションの収集をアクティブにします。ユーザーインタラクションを参照してください。
`interactions.eventNames`		インストルメンテーションがユーザーインタラクションとして捕捉する DOM イベントの配列。`SplunkRum.DEFAULT_AUTO_INSTRUMENTED_EVENT_NAMES` プロパティにアクセスすることで、デフォルト値にアクセスできます。
`longtask`	`true`	長いタスクの収集をアクティブにします。長いタスクを参照してください。
`socketio`	`false`	socket.io メッセージの収集をアクティブにします。Socket.io メッセージを参照してください。
`postload`	`true`	ロードイベントの後にロードされたリソースの収集をアクティブにします。ロード後のリソースを参照してください。
`socketio.target`	`'io'`	socket.io クライアントをロードするグローバル変数名、または `io` オブジェクト。Socket.io メッセージを参照してください。
`visibility`	`false`	可視性イベントの収集をアクティブにします。可視性を参照してください。
`websocket`	`false`	ウェブソケットのライフサイクルイベントの収集をアクティブにします。ウェブソケットを参照してください。
`webvitals`	`true`	Google Web Vitalsメトリクスの収集を有効にします。ウェブバイタルを参照してください。
`xhr`	`true`	XMLHttpRequest イベントの収集をアクティブにします。XHRとFetchインストルメンテーションを参照してください。

サンプリング設定 🔗

デフォルトでは、ブラウザ RUMエージェントは、すべてのユーザーからすべてのデータを収集します。tracer プロパティにカスタムサンプラーを渡すことで、サンプリングを調整できます。

次の例は、サンプリングをログインしているユーザーに制限する方法を示しています：

<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
   var shouldTrace = isUserLoggedIn();

   SplunkRum.init({
      realm: '<realm>',
      rumAccessToken: '<your_rum_token>',
      applicationName: '<application-name>',
      tracer: {
         sampler: shouldTrace ? new AlwaysOnSampler() : new SplunkRum.AlwaysOffSampler(),
      },
   });
</script>

// When using npm you can get samplers directly from @opentelemetry/core
import {AlwaysOnSampler, AlwaysOffSampler} from '@opentelemetry/core';
import SplunkOtelWeb from '@splunk/otel-web';

SplunkOtelWeb.init({
   beaconEndpoint: 'https://rum-ingest..signalfx.com/v1/rum',
   rumAccessToken: '<your_rum_token>',
   applicationName: '<application-name>',
   tracer: {
      sampler: userShouldBeTraced() ? new SplunkRum.AlwaysOnSampler() : new SplunkRum.AlwaysOffSampler(),
   },
});

Splunk Distribution of OpenTelemetry JS for Web には、以下のサンプラーが含まれています：

サンプラー	説明
`AlwaysOnSampler`	すべてのリクエストでサンプリングを有効にします。これはデフォルトのサンプラーです。
`AlwaysOffSampler`	全リクエストで停止されたサンプリング。
`ParentBasedSampler`	親トレースのサンプラー設定を継承します。
`SessionBasedSampler`	セッションベースのサンプリング。セッションベースのサンプラーを参照してください。

セッションベースのサンプラー 🔗

Splunk Distribution of OpenTelemetry JS for Web には、セッションをサポートするカスタムサンプラーが含まれています。セッション比率はトレース比率よりも望ましい状態です。

セッションベースのサンプラーには、以下の方法でアクセスできます：

Splunk CDN ビルドを使用する場合は、SplunkRum.SessionBasedSampler エクスポートを使用します。
npmパッケージを使用する場合は、SessionBasedSampler エクスポートを使用します。

セッションベースのサンプラーは、以下の設定を受け付けます：

オプション	タイプ	デフォルト値	説明
`ratio`	`number`	`1.0`	報告されたセッションの割合、範囲は `0.0` から `1.0` まで。
`sampled`	`Sampler`	`AlwaysOnSampler`	セッションのサンプリング時に使用するサンプラー。
`notSampled`	`Sampler`	`AlwaysOffSampler`	セッションをサンプリングしない場合に使用するサンプラー。

次の例は、セッションの半分からRUMデータを収集する方法を示しています：

<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: '<application-name>',
    tracer: {
      sampler: new SplunkRum.SessionBasedSampler({
      ratio: 0.5
      }),
    },
  });
</script>

import SplunkOtelWeb, {SessionBasedSampler} from '@splunk/otel-web';

SplunkOtelWeb.init({
  realm: '<realm>',
  rumAccessToken: '<your_rum_token>',
  applicationName: '<application-name>',
  tracer: {
      sampler: new SessionBasedSampler({
        ratio: 0.5
      }),
  },
});

非同期トレース設定 🔗

プロミスチェーンになるユーザーインタラクションのような、非同期に起こるトレースは、親アクティビティから切り離される可能性があります。この問題を回避するために、ブラウザ RUMエージェントは、以下のプロパティまたはパターンを使用しているときに発生するトレースと親トレースを接続するカスタムコンテキストマネージャーを含んでいます：

setTimeout 34ms以下のタイムアウト
setImmediate
requestAnimationFrame
Promise.then / catch / finally
textNode 上の MutationObserver
MessagePort
ハッシュ・ベース・ルーター

非同期トレース・リンクはデフォルトで有効になっています。互換性の問題がある場合は、context.async プロパティを false に設定することで、無効にすることができます。

コンテキストマネージャーにより、Splunk RUM はコンポーネントが最初にレンダリングされたときに実行されたリクエストを、アプリケーションがコンポーネントをページに追加する原因となったユーザーインタラクションにリンクさせることができます。XMLHttpRequest イベントと Fetch API イベントは、promise メソッドを介して親コンテキストを保持するようにパッチされます。

制限事項 🔗

非同期トレースを使用する場合、以下の制限が適用されます：

async/await 関数はサポートされていません。Babelを使用して古いブラウザをターゲットにコードをダウンコンパイルします。

document.getElementById('save-button').addEventListener('click', async () => {
  const saveRes = await fetch('/api/items', {method: 'POST'});

  const listRes = await fetch('/api/items'); // Can be disconnected from click event when not transpiled
});

プロミスベースの実装によってロードされたコードだけが、親インタラクションにリンクされます。

コンテキスト伝播の設定 🔗

ブラウザ RUM エージェントは、Server-Timing ヘッダーから traceparent データを収集するため、コンテキストプロパゲータを登録しません。必要であれば、OpenTelemetry API を使ってコンテキストプロパゲータを登録できます：

import {propagation} from '@opentelemetry/api';
import {B3Propagator} from '@opentelemetry/propagator-b3';

propagation.setGlobalPropagator(new B3Propagator());

OpenTelemetry APIを直接呼び出す場合は、使用しているAPIのバージョンが、ブラウザ RUMエージェントで使用されているものと一致していることを確認してください。

エクスポート設定 🔗

By default, the Browser RUM agent uses the Zipkin exporter to send data to Splunk Observability Cloud.

バージョン 0.17.0 以降では、OTLP エクスポーターを使用するように RUM エージェントを設定できます。次の例は、OTLP エクスポーターを使用するように RUM インストルメンテーションを設定する方法を示しています：

   SplunkRum.init({
      realm: '<realm>',
      rumAccessToken: '<your_rum_token>',
      applicationName: '<application-name>',
      deploymentEnvironment: '<deployment-env>',
      exporter: {
         otlp: true
      },
   });

beaconEndpoint を手動で設定する場合は、https://rum-ingest.<realm>.signalfx.com/v1/rumotlp を OTLP エンドポイントとして使用します。exporter.otlp が true で、realm が設定されている場合、エンドポイントは自動的に設定されます。

ブラウザRUMエージェントが使用するクッキー 🔗

ブラウザ RUMエージェントは、以下のクッキーを使用して、トレースをセッションにリンクします：

Name	目的	コメント
`__splunk_rum_sid`	セッションIDを格納します。	デフォルトでは、セッションは最後のユーザー操作から15分間持続します。セッションの最大持続時間は4時間です。

このページは 2024年05月14日に最終更新されました。

Related Topics