WebSocket 永続接続収集¶

RUM SDK 3.3.6 以降では、ブラウザのネイティブ WebSocket 接続を RUM Resource として集約し、ハンドシェイク、メッセージトラフィック、インバウンドアイドル、送信バックログ、クローズ状態を分析できるようになりました。

この機能は現在実験的な機能であり、デフォルトでは無効になっています。SDK は WebSocket メッセージの本文を読み取ったりアップロードしたりすることはありません。

収集を有効にする¶

NPM¶

import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "websocket-client",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  enableExperimentalFeatures: ["track_websockets"],
})

スリム版 RUM パッケージでも同じ設定を使用します：

import { datafluxRum } from "@cloudcare/browser-rum-slim"

CDN¶

<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_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "websocket-client",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      enableExperimentalFeatures: ["track_websockets"],
    })
</script>

上記の例ではパブリック OpenWay を使用しています。DataKit に直接接続する場合は、site と clientToken を datakitOrigin に置き換えてください。両方のレポートアドレスを同時に設定しないでください。

enableExperimentalFeatures は配列である必要があります。文字列 "track_websockets" を直接指定しても収集は有効になりません。

初期化のタイミング¶

RUM は、業務が WebSocket 接続を作成する前に初期化する必要があります：

datafluxRum.init({
  // その他の設定
  enableExperimentalFeatures: ["track_websockets"],
})

const socket = new WebSocket("wss://example.com/socket")

以下の接続は収集されません：

• RUM 初期化前に作成された接続
• 初期化前にキャッシュされた元の WebSocket コンストラクタを使用して作成された接続
• Web Worker または Service Worker 内で作成された接続
• window.WebSocket を経由しないその他のトランスポート実装
• WebSocketStream で作成された接続

収集を有効にしても、ネイティブ WebSocket の構築方法、静的定数、instanceof、ビジネスイベントリスナー、send() の戻り値の動作は変更されません。

収集モデル¶

各 WebSocket セッションセグメントは、1 つの RUM Resource として生成されます：

type = resource
resource.type = websocket

Resource は以下のタイミングで生成されます：

1. ブラウザが WebSocket close イベントを受信したとき
2. 現在の RUM セッションが期限切れになったとき
3. ページが beforeunload をトリガーしたとき
4. SDK が現在の収集インスタンスを停止したとき

WebSocket は永続接続です。接続がまだ開いている間は、Network に最終的な RUM Resource が一時的に表示されないのは正常な動作です。SDK は現在のところ、定期的に接続スナップショットをアップロードしません。

ページのリフレッシュ、クローズ、または移動が発生した場合、SDK は beforeunload フェーズで可能な限り決済と送信を試みます。ページプロセスが強制終了されたり、ブラウザがクラッシュしたり、デバイスの電源が切れたりした場合、JavaScript が実行される機会がないため、最後の接続 Resource が失われる可能性があります。

正常クローズ¶

ブラウザが close を受信した場合：

resource.websocket.tracking_end_reason = close_event

イベントには、クローズコード、クローズ理由、was_clean が含まれます。

セッション期限切れ¶

セッションが期限切れになった場合、まだ開いている接続は現在のデータに基づいて決済されます：

resource.websocket.tracking_end_reason = session_end

この場合、ビジネス WebSocket はクローズされないため、クローズコード、クローズ理由、was_clean は存在しない可能性があります。新しいセッションが確立されると、SDK は同じ物理接続に対して新しい統計セグメントを開始し、同じ connection_id を保持し、メッセージカウントとセグメント時間をリセットします。

セッションが期限切れになり、まだ更新されていない間のメッセージは、どのセッションにもカウントされません。この期間中に新しく作成され、更新時にもまだ開いている接続は、新しいセッションの更新時点から統計が開始されます。

ページアンロード¶

ページが beforeunload をトリガーした場合：

resource.websocket.tracking_end_reason = page_exit

接続が必ずしもブラウザの close イベントをトリガーするとは限らないため、クローズフィールドは存在しない可能性があります。

ハンドシェイク失敗¶

接続が一度も open をトリガーせずに close に入った場合：

resource.websocket.handshake_succeeded = false

この場合、setup_duration はコンストラクトからクローズまたはセッション決済までの時間を示し、正常なハンドシェイクにかかった時間を示すものではありません。ブラウザは通常、異常クローズを示すためにクローズコード 1006 を使用します。実際の値はブラウザのイベントに依存します。

メッセージ統計¶

SDK はメッセージ数とバイト数のみを統計し、本文は収集しません：

例えば、文字列 你好 は UTF-8 で 6 バイトとして統計され、JavaScript の文字列長である 2 ではありません。

View の所属¶

1 つの WebSocket セッションセグメントは、複数の RUM View にまたがる可能性があります。Resource は追加で以下の情報を記録します：

• start_view_id：現在のセグメント開始時に存在していた View
• end_view_id：クローズまたは決済時に存在していた View

セグメントがページをまたぐ場合、これらの 2 つの ID は異なる可能性があります。Resource は、セグメントの開始時刻に基づいて RUM イベントパイプラインに入ります。

レポートフィールド¶

beforeSend で event.resource.websocket を読み取ることができます。最終的な intake では、フィールドは resource_websocket_* に変換されます。

基本 Resource フィールド¶

WebSocket Resource には HTTP レスポンスがないため、resource_status、resource_method、TTFB、ダウンロードサイズ、HTTP タイミングはありません。

接続フィールド¶

メッセージフィールド¶

buffered_amount_max は send() 呼び出し前のサンプリングピーク値であり、ブラウザの送信キューを継続的に監視した値ではありません。

クローズフィールド¶

セッションの期限切れやページアンロードによる決済時には、これらのフィールドは存在しない可能性があります。

beforeSend の使用¶

WebSocket Resource をチェック、補完、またはフィルタリングできます：

datafluxRum.init({
  // その他の設定
  enableExperimentalFeatures: ["track_websockets"],
  beforeSend(event, domainContext) {
    if (
      event.type === "resource" &&
      event.resource?.type === "websocket"
    ) {
      event.context = {
        ...event.context,
        socket_channel: "notifications",
      }

      console.debug(
        "WebSocket completed",
        event.resource.websocket,
        domainContext?.webSocket
      )
    }

    return true
  },
})

WebSocket Resource の domainContext には以下が含まれます：

domainContext.isWebSocket = true
domainContext.webSocket = ネイティブ WebSocket インスタンス

domainContext は beforeSend コールバック内でのみ使用され、アップロードされることはありません。

false を返すことで、特定の接続を破棄できます：

beforeSend(event) {
  if (
    event.type === "resource" &&
    event.resource?.type === "websocket" &&
    event.resource.url.includes("/health-stream")
  ) {
    return false
  }

  return true
}

プライバシーとセキュリティ¶

SDK は完全な WebSocket URL を収集し、URL のクエリパラメータを解析します。パスワード、長期間有効なトークン、ID 番号などの機密値を URL に配置しないでください。

収集を有効にしても、ページの CSP connect-src、サーバー側の Origin 検証、その他のブラウザのセキュリティポリシーはバイパスされません。また、ハンドシェイクリクエストにカスタムトレースヘッダーが注入されることもありません。

サードパーティライブラリが RUM の初期化後に window.WebSocket を呼び出す限り、その基盤となる接続は収集されます：

• 自動再接続によって新しい接続が作成されるたびに、新しい connection_id と Resource が生成されます。
• 1 つの接続が複数のビジネストピックを再利用する場合、SDK は接続レベルの集約のみを提供します。
• HTTP long polling フェーズは、引き続き XHR または fetch Resource として収集されます。

接続の検証¶

1. ブラウザの開発者ツールを開き、ビジネス WebSocket が接続され、メッセージが生成されていることを確認します。
2. 能動的に socket.close(1000, "done") を実行します。
3. Network で /v1/write/rum をフィルタリングします。
4. リクエストデータ内で resource_type=websocket を検索します。
5. handshake_succeeded、メッセージ数、バイト数、クローズフィールドを確認します。

接続がずっとクローズされない場合は、セッションの期限切れを待って tracking_end_reason=session_end を確認できます。ページをリフレッシュすると、tracking_end_reason=page_exit が表示されるはずです。この送信は、ページ終了フェーズでのベストエフォート型のレポートです。

よくある質問¶

設定しても WebSocket Resource が表示されない¶

以下の順序で確認してください：

1. enableExperimentalFeatures が "track_websockets" を含む配列であること
2. RUM が接続作成前に初期化されていること
3. 現在のセッションが sessionSampleRate に該当していること
4. 接続がすでにクローズされているか、セッションが期限切れになっていないこと
5. beforeSend が false を返していないこと
6. 接続が Worker によって作成されていないこと

WebSocket error を受信したが、Resource がまだない¶

SDK は close またはセッション決済時に最終イベントを生成します。error イベントだけで個別に決済することはありません。

handshake_succeeded=false¶

ブラウザが open をトリガーしませんでした。WebSocket URL、TLS 証明書、CSP connect-src、リバースプロキシの Upgrade 設定、サーバー側の Origin 検証、認証を確認してください。

メッセージサイズが 0¶

データ型が string、ArrayBuffer、TypedArray、DataView、または Blob であることを確認してください。SDK は任意のオブジェクトをシリアライズしてサイズを推定することはありません。

HTTP ステータスコードが表示されない¶

ブラウザの WebSocket API は、ページにハンドシェイクの HTTP ステータスコードを公開しません。そのため、WebSocket Resource には resource_status がありません。