Resource Hook 導入ガイド (SDK バージョン要件 `>= 3.3.0`)¶

説明¶

Resource Hook は、自動収集された resource イベントにリクエストレベルのビジネスフィールドを追加するために使用します。

ユースケース：

リクエスト開始前にビジネスコンテキストを書き込む必要がある場合
レスポンス返却後もフィールドを追加し続ける必要がある場合
最終的に報告される resource イベントに、これら両方のデータを同時に含める必要がある場合

この機能は fetch と XMLHttpRequest の両方をサポートしています。

動作方式¶

createResourceTrackerId() を使用してトラッカーIDを作成する
そのIDをリクエストヘッダー x-rum-resource-id に設定する
setResourceContext() でリクエスト前のコンテキストを書き込む
appendResourceContext() でレスポンス後のコンテキストを追加する
finishResource() を呼び出して、最終的なトラッキングリソースの報告をトリガーする

リクエストに x-rum-resource-id が含まれていない場合、SDK は従来の通常のリソース自動収集のフローを継続します。

Public API¶

const resourceId = DATAFLUX_RUM.createResourceTrackerId()

DATAFLUX_RUM.setResourceContext(resourceId, { order_id: '123' })
DATAFLUX_RUM.appendResourceContext(resourceId, { result: 'success' })
DATAFLUX_RUM.finishResource(resourceId)
DATAFLUX_RUM.getResource(resourceId)

API の意味：

createResourceTrackerId() 新しいトラッカーIDを作成する
setResourceContext(resourceId, context) 現在のトラッカーのコンテキストを上書きする
appendResourceContext(resourceId, context) 現在のトラッカーのコンテキストにさらにフィールドを追加する
finishResource(resourceId) このトラッキングリソースの準備が完了したことを示す。リクエストが既に完了している場合は即座に報告をトリガーし、まだ完了していない場合はSDKがリクエスト完了後に報告する
getResource(resourceId) 現在のトラッカーのスナップショットを返す。主にデバッグ用

Fetch の例¶

const resourceId = window.DATAFLUX_RUM.createResourceTrackerId()

window.DATAFLUX_RUM.setResourceContext(resourceId, {
  order_id: '123',
  scene: 'checkout'
})

fetch('/api/order/detail', {
  headers: {
    'x-rum-resource-id': resourceId
  }
})
  .then((response) => {
    window.DATAFLUX_RUM.appendResourceContext(resourceId, {
      result: 'success',
      response_status: response.status
    })
    window.DATAFLUX_RUM.finishResource(resourceId)
    return response
  })
  .catch((error) => {
    window.DATAFLUX_RUM.appendResourceContext(resourceId, {
      result: 'error',
      error_message: error.message
    })
    window.DATAFLUX_RUM.finishResource(resourceId)
    throw error
  })

XHR の例¶

const resourceId = window.DATAFLUX_RUM.createResourceTrackerId()

window.DATAFLUX_RUM.setResourceContext(resourceId, {
  order_id: '123',
  scene: 'checkout'
})

const xhr = new XMLHttpRequest()
xhr.open('GET', '/api/order/detail', true)
xhr.setRequestHeader('x-rum-resource-id', resourceId)

xhr.addEventListener('load', () => {
  window.DATAFLUX_RUM.appendResourceContext(resourceId, {
    result: 'success',
    response_status: xhr.status
  })
  window.DATAFLUX_RUM.finishResource(resourceId)
})

xhr.addEventListener('error', () => {
  window.DATAFLUX_RUM.appendResourceContext(resourceId, {
    result: 'error',
    error_message: 'xhr_error'
  })
  window.DATAFLUX_RUM.finishResource(resourceId)
})

xhr.send()

トレースケースの例¶

同じリクエストにトレースIDも注入する必要がある場合は、x-rum-resource-id を保持し、リクエストURLがトレーシングのホワイトリストに設定されていることを確認してください。以下のCDNの例ではデフォルトの ddtrace を使用しています。他のタイプを明示的に指定する必要がある場合は、初期化パラメータの traceType の説明を参照してください。

window.DATAFLUX_RUM.init({
  // ...
  allowedTracingUrls: [window.location.origin]
})

その後、通常通りトラッキングリクエストを送信します：

const resourceId = window.DATAFLUX_RUM.createResourceTrackerId()

window.DATAFLUX_RUM.setResourceContext(resourceId, {
  scene: 'checkout'
})

fetch('/api/order/detail', {
  headers: {
    'x-rum-resource-id': resourceId
  }
})
  .then((response) => {
    window.DATAFLUX_RUM.appendResourceContext(resourceId, {
      trace_expected: 'true',
      response_status: response.status
    })
    window.DATAFLUX_RUM.finishResource(resourceId)
    return response
  })

最終的なトラッカースナップショット内の rawRumEvent._gc には traceId と spanId が含まれる可能性があります。

デバッグ方法¶

任意の時点で現在のトラッカースナップショットを確認できます：

const snapshot = window.DATAFLUX_RUM.getResource(resourceId)
console.log(snapshot)

典型的なスナップショット構造：

{
  trackerId: 'uuid',
  status: 'request_collected',
  context: {
    order_id: '123',
    result: 'success'
  },
  resource: {
    type: 'fetch',
    url: '/api/order/detail',
    method: 'GET',
    status: 200
  },
  rawRumEvent: {
    type: 'resource',
    _gc: {
      traceId: '...',
      spanId: '...'
    }
  }
}

現在のステータス値は次のとおりです：

created
request_collected
finished
flushed
timeout_flushed
cleared

タイムアウト動作¶

ビジネスが finishResource() を呼び出さない場合、SDK は 30s 後にこのトラッキングリソースを自動的にフラッシュします。

ここで最も誤解されやすい点は次のとおりです：

この 30s はリクエスト完了後からカウントが始まります
リクエスト開始時からカウントが始まるわけではありません

実際のタイミングは次のとおりです：

リクエスト開始
リクエスト完了
SDK が x-rum-resource-id を介してこのリソースに関連付け
この時点でまだ finishResource() が呼び出されていない場合、SDK は最大 30s 待機
時間切れ後、自動的に timeout_flushed ステータスで報告

これにより、トラッキングリクエストが長時間保留状態になるのを防ぎつつ、ビジネスコードに「リクエスト完了後にレスポンスコンテキストを追加する」ための猶予期間を確保できます。

タイミングの説明¶

リクエスト完了前に finishResource() を呼び出した場合、SDK はすぐに報告せず、まずトラッカーを finished とマークし、リクエストが実際に完了してからフラッシュします。
リクエスト完了後に finishResource() を呼び出した場合、SDK は即座にフラッシュします。
最後まで finishResource() を呼び出さなかった場合は、上記の「リクエスト完了後、30s 待機してから自動フラッシュ」のロジックが適用されます。

注意事項¶

ビジネスリクエストはカスタムヘッダー x-rum-resource-id を許可する必要があります
リクエストにこのヘッダーが含まれていない場合、自動的に通常のリソース収集にダウングレードされます
ヘッダーに指定されたトラッカーIDが存在しない場合も、自動的に通常のリソース収集にダウングレードされます
getResource() は主にデバッグ用であり、ビジネスロジックの依存として使用することは推奨されません

Resource Hook 導入ガイド (SDK バージョン要件 >= 3.3.0)¶

説明¶