Resource Hook 接入指南 (SDK 버전 요구 사항 `>= 3.3.0`)¶

개요¶

Resource Hook은 자동 수집된 resource 이벤트에 요청 수준의 비즈니스 필드를 추가하는 기능입니다.

사용 사례:

요청 시작 전에 비즈니스 컨텍스트를 기록해야 하는 경우
응답 반환 후에도 필드를 계속 추가해야 하는 경우
최종으로 전송되는 resource 이벤트에 두 부분의 데이터를 모두 포함해야 하는 경우

이 기능은 fetch와 XMLHttpRequest를 모두 지원합니다.

작동 방식¶

createResourceTrackerId()를 사용하여 tracker id 생성
해당 id를 요청 헤더 x-rum-resource-id에 추가
setResourceContext()로 요청 전 컨텍스트 기록
appendResourceContext()로 응답 후 컨텍스트 추가
finishResource()를 호출하여 최종 tracked resource 전송

요청에 x-rum-resource-id가 포함되지 않은 경우 SDK는 기존의 일반 resource 자동 수집 방식을 그대로 사용합니다.

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() 새로운 tracker id 생성
setResourceContext(resourceId, context) 현재 tracker의 컨텍스트 덮어쓰기
appendResourceContext(resourceId, context) 현재 tracker의 컨텍스트에 필드 추가
finishResource(resourceId) tracked resource가 종료 준비가 되었음을 나타냅니다. 요청이 이미 완료된 경우 즉시 전송되며, 요청이 아직 완료되지 않은 경우 SDK는 요청이 완료될 때까지 기다렸다가 전송합니다.
getResource(resourceId) 현재 tracker의 스냅샷을 반환하며, 주로 디버깅에 사용됩니다.

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()

Trace 시나리오 예제¶

동일한 요청에 trace id도 추가해야 하는 경우, x-rum-resource-id를 유지하고 요청 URL이 tracing 화이트리스트에 등록되어 있는지 확인해야 합니다. 다음 CDN 예제는 기본 ddtrace를 사용합니다. 다른 유형을 명시적으로 지정해야 하는 경우 초기화 파라미터의 traceType 설명을 참조하세요.

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

그런 다음 평소처럼 tracked request를 전송합니다:

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
  })

최종 tracker 스냅샷의 rawRumEvent._gc에는 traceId와 spanId가 포함될 수 있습니다.

디버깅 방법¶

언제든지 현재 tracker 스냅샷을 확인할 수 있습니다:

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는 30초 후에 이 tracked resource를 자동으로 flush합니다.

여기서 가장 오해하기 쉬운 점은 다음과 같습니다:

이 30초는 요청이 완료된 이후부터 계산됩니다.
요청 시작 시점부터 계산되는 것이 아닙니다.

실제 타임라인은 다음과 같습니다:

요청 시작
요청 완료
SDK가 x-rum-resource-id를 통해 이 resource를 연결
이 시점에 finishResource()가 호출되지 않은 경우, SDK는 최대 30초 더 대기
시간이 초과되면 timeout_flushed 상태로 자동 전송

이렇게 하면 tracked request가 장기간 pending 상태로 남는 것을 방지하고, 비즈니스 코드에 "요청 완료 후 응답 컨텍스트를 추가할 수 있는" 여유 시간을 제공합니다.

타이밍 설명¶

요청 완료 전에 finishResource()를 호출하면 SDK가 즉시 전송하지 않고 tracker를 finished로 표시한 후, 요청이 실제로 완료될 때까지 기다렸다가 flush합니다.
요청 완료 후에 finishResource()를 호출하면 SDK가 즉시 flush합니다.
finishResource()를 전혀 호출하지 않으면 위의 "요청 완료 후 30초 대기 후 자동 flush" 로직이 적용됩니다.

주의 사항¶

비즈니스 요청은 사용자 정의 헤더 x-rum-resource-id를 허용해야 합니다.
요청에 이 헤더가 포함되지 않은 경우 자동으로 일반 resource 수집으로 대체됩니다.
헤더에 포함된 tracker id가 존재하지 않는 경우에도 자동으로 일반 resource 수집으로 대체됩니다.
getResource()는 주로 디버깅 용도이며, 비즈니스 로직에 의존하는 것은 권장되지 않습니다.

Resource Hook 接入指南 (SDK 버전 요구 사항 >= 3.3.0)¶

개요¶