미니프로그램 SDK 원격 구성 및 강제 샘플링¶

미니프로그램 SDK 2.2.16 이상 버전에서는 미니프로그램을 다시 배포하지 않고도 샘플링 비율 등의 런타임 구성을 조정할 수 있으며, 원격으로 전달된 비즈니스 필드에 따라 지정된 사용자의 현재 Session을 강제로 수집할 수 있습니다.

원격 구성 활성화¶

초기화 시 remoteConfiguration: true를 설정합니다. SDK는 즉시 로컬 구성에 따라 시작되며, 원격 구성 요청은 첫 화면 수집을 차단하지 않습니다.

이전 버전에서는 remoteConfigration 철자를 사용했으며, 2.2.16에서도 여전히 호환되지만 신규 프로젝트는 remoteConfiguration을 사용해야 합니다.

const { datafluxRum } = require('@cloudcare/rum-miniapp')

datafluxRum.init({
  applicationId: 'appid_xxxxxxx',
  site: 'https://rum-openway.guance.com',
  clientToken: 'client_token_xxxxx',
  service: 'miniapp-demo',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 20,
  allowedTracingUrls: ['https://api.example.com/v1/'],
  allowTraceHeaderWithoutSession: true,
  remoteConfiguration: true,
  remoteConfigurationFetchTimeout: 3000,
})

파라미터	타입	기본값	설명
`sessionSampleRate`	number	`100`	`sampleRate`의 호환 별칭, 범위는 `0`~`100`입니다. 두 값을 동시에 설정하면 `sampleRate`가 우선 적용됩니다.
`allowedTracingUrls`	Array	`[]`	Trace Header 삽입을 허용하는 전체 요청 URL 일치 목록입니다. 문자열은 URL 접두사로 일치하며, 로컬 구성에서는 정규식, 함수 및 `{ match, traceType }`도 지원합니다.
`allowedTracingOrigins`	Array		폐기된 호환 구성으로, 요청 Origin만 기준으로 일치합니다. 두 값을 동시에 설정하면 `allowedTracingUrls`가 우선 적용됩니다.
`allowTraceHeaderWithoutSession`	boolean	`false`	현재 Session이 샘플링에 포함되지 않았을 때도 `allowedTracingUrls`에 일치하는 요청에 Trace Header를 삽입할지 여부입니다. 활성화해도 해당 Session의 RUM 데이터가 업로드되지는 않습니다.
`remoteConfiguration`	boolean	`false`	원격 구성을 비동기로 가져와 적용할지 여부입니다.
`remoteConfigration`	boolean	`false`	이전 철자 호환 항목으로, 신규 프로젝트에는 권장되지 않습니다.
`remoteConfigurationFetchTimeout`	number	`3000`	원격 구성 요청 제한 시간(밀리초)입니다. 요청 실패 또는 시간 초과 시 로컬 구성을 계속 사용합니다.

활성화 후 SDK는 다음 주소로 요청을 보냅니다.

{datakitOrigin|datakitUrl|site}/v1/env_variable?app_id={applicationId}

공용 DataWay를 사용하는 경우 요청에 clientToken도 함께 전송됩니다. 해당 도메인을 WeChat 미니프로그램의 request 허용 도메인 화이트리스트에 추가해야 합니다.

구성 전달 형식¶

원격 구성 키는 다음 형식을 사용합니다.

R.{applicationId}.{구성명}

예시:

{
  "R.appid_xxxxxxx.sessionSampleRate": 20,
  "R.appid_xxxxxxx.vip_id": "[\"user-1\", \"user-2\"]"
}

SDK는 R.{applicationId}. 접두사를 제거합니다. 비즈니스 로직은 getRemoteConfiguration()을 통해 다음을 획득합니다.

{
  "sessionSampleRate": 20,
  "vip_id": "[\"user-1\", \"user-2\"]"
}

현재 원격 업데이트가 지원되는 항목:

sampleRate
sessionSampleRate
service
env
version
trackInteractions
traceType
traceId128Bit
allowedTracingUrls
allowedTracingOrigins
allowTraceHeaderWithoutSession

sessionSampleRate는 sampleRate에 따라 적용됩니다. vip_id와 같은 사용자 정의 필드는 SDK 동작을 자동으로 변경하지 않으므로, 비즈니스 코드에서 읽어서 직접 처리해야 합니다.

원격 구성은 JSON을 사용하므로, allowedTracingUrls는 문자열 또는 { "match": "https://api.example.com/v1/", "traceType": "w3c_traceparent" } 형태의 객체만 전달할 수 있습니다. 정규식과 함수는 로컬 초기화 구성에만 작성할 수 있습니다.

allowedTracingUrls는 @cloudcare/rum-miniapp 2.2.19 이상 버전이 필요합니다. 이전 버전에서는 allowedTracingOrigins를 계속 사용합니다.

샘플링되지 않은 Session의 Trace Header¶

기본적으로 현재 Session이 RUM 샘플링에 포함된 경우에만 SDK가 allowedTracingUrls에 일치하는 요청에 Trace Header를 삽입합니다.

allowTraceHeaderWithoutSession: true를 설정하면 현재 Session이 샘플링에 포함되지 않았더라도 SDK가 조건에 맞는 요청에 Trace Header를 계속 삽입합니다. 이 구성은 강제 샘플링을 수행하거나 새 Session을 생성하지 않으며, 샘플링되지 않은 Session의 View, Action, Resource, Error 등의 RUM 데이터를 업로드하지도 않습니다.

이 구성은 원격 업데이트를 지원합니다. 원격 값이 반환되기 전까지는 로컬 구성에 따라 처리되며, 반환 후에는 이후 요청에만 영향을 미칩니다.

원격 구성 획득¶

datafluxRum.init() 후에 getRemoteConfiguration(callback)을 호출합니다.

datafluxRum.getRemoteConfiguration(function (remoteConfig) {
  console.log('remote config:', remoteConfig)
})

요청이 완료되지 않은 경우, 콜백은 해당 요청이 완료될 때까지 대기합니다.
요청이 이미 완료된 경우, 콜백은 즉시 캐시된 결과를 수신하며, 추가 요청을 보내지 않습니다.
각 콜백은 독립적인 복사본을 수신하므로, 반환된 객체를 수정해도 SDK 내부 구성이 변경되지 않습니다.
원격 구성이 활성화되지 않았거나, 요청 실패, 시간 초과, 또는 반환된 내용을 파싱할 수 없는 경우 콜백은 빈 객체 {}를 수신합니다.

현재 Session 강제 수집¶

setForcedSession()은 현재 Session을 강제로 수집하는 데 사용됩니다. 로컬 또는 원격 샘플링 비율에 포함되지 않았더라도 호출 후의 RUM 데이터는 계속 업로드되며, 다음 태그가 함께 전송됩니다.

session_is_forced=true

다음 예시는 원격으로 전달된 VIP 사용자 목록을 기준으로 강제 수집을 수행합니다.

var currentUserId = 'user-1'

datafluxRum.setUser({ id: currentUserId })
datafluxRum.getRemoteConfiguration(function (remoteConfig) {
  var vipIds = remoteConfig && remoteConfig.vip_id

  if (typeof vipIds === 'string') {
    try {
      vipIds = JSON.parse(vipIds)
    } catch (error) {
      vipIds = []
    }
  }

  if (Array.isArray(vipIds) && vipIds.map(String).indexOf(currentUserId) !== -1) {
    datafluxRum.setForcedSession()
    datafluxRum.addRumGlobalContext('vip_force_collect', true)
  }
})

setForcedSession()은 호출 이후의 데이터에만 영향을 미치며, 이전에 이미 폐기된 데이터를 다시 전송하지는 않습니다. 강제 상태는 현재 Session에만 적용되며, Session이 만료되면 최신 샘플링 비율에 따라 다시 계산됩니다.

Session 및 런타임 동작¶

Session은 applicationId별로 독립적으로 저장되며, 서로 다른 RUM 애플리케이션 간에 Session ID나 샘플링 결과가 재사용되지 않습니다.
15분 연속 활동이 없으면 새 Session이 생성되며, 단일 Session의 최대 길이는 4시간입니다.
페이지 진입, 클릭, 터치, 입력 및 선언된 페이지 스크롤은 Session을 연장합니다. trackInteractions를 비활성화하면 자동 Action 수집만 중단되며, Session 활동 인식에는 영향을 미치지 않습니다.
원격 구성 반환 이전의 데이터는 로컬 구성에 따라 처리되며, 소급하여 재계산되지 않습니다.
이번 초기화에서 새로 생성되었고 아직 강제 샘플링되지 않은 Session의 경우, 원격 샘플링 비율 반환 후 샘플링 결과를 다시 계산할 수 있습니다. 저장소에서 복원된 Session은 원래 샘플링 결정을 유지합니다.
SDK는 wx.request 및 wx.downloadFile을 프록시할 때 비즈니스 호출의 원래 반환 값과 Promise 동작을 유지합니다.