ミニプログラム SDK のリモート設定と強制サンプリング¶

ミニプログラム SDK 2.2.16 以降では、ミニプログラムを再公開しなくてもサンプリングレートなどの実行時設定を調整できるほか、リモートから配信された業務フィールドに基づいて、指定したユーザーの現在のセッションを強制的に収集することもできます。

リモート設定を有効にする¶

初期化時に 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`	現在のセッションがサンプリング対象外の場合でも、`allowedTracingUrls` に一致するリクエストに Trace Header を注入するかどうか。有効にしても、そのセッションの RUM データは送信されません
`remoteConfiguration`	boolean	`false`	リモート設定を非同期で取得して適用するかどうか
`remoteConfigration`	boolean	`false`	旧スペル互換用。新規プロジェクトでは推奨しません
`remoteConfigurationFetchTimeout`	number	`3000`	リモート設定リクエストのタイムアウト時間（ミリ秒）。失敗またはタイムアウトした場合はローカル設定が継続して使用されます

有効にすると、SDK は次のアドレスにリクエストを送信します。

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

パブリック DataWay を使用する場合、リクエストには clientToken も含まれます。該当のドメインを WeChat ミニプログラムのリクエスト許可ドメインのホワイトリストに追加する必要があります。

設定配信フォーマット¶

リモート設定のキーは次の形式を使用します。

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 を使用してください。

未サンプリングセッションの Trace Header¶

デフォルトでは、現在のセッションが RUM サンプリングの対象となった場合のみ、SDK は allowedTracingUrls に一致するリクエストに Trace Header を注入します。

allowTraceHeaderWithoutSession: true を設定すると、現在のセッションがサンプリング対象外でも、条件に一致するリクエストに Trace Header が注入されます。この設定では強制的なサンプリングや新しいセッションの作成は行われず、未サンプリングのセッションの View、Action、Resource、Error などの RUM データも送信されません。

この設定はリモート更新に対応しています。リモート値が返されるまではローカル設定に従い、返された後はそれ以降のリクエストにのみ影響します。

リモート設定の取得¶

datafluxRum.init() の後に getRemoteConfiguration(callback) を呼び出します。

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

リクエストが完了していない場合、コールバックは今回のリクエストの完了を待ちます。
リクエストがすでに完了している場合、コールバックはキャッシュされた結果を即座に受け取り、新たにリクエストを発行しません。
各コールバックは独立したコピーを受け取るため、返されたオブジェクトを変更しても SDK 内部の設定は変わりません。
リモート設定が有効でない場合、リクエストが失敗またはタイムアウトした場合、あるいは返された内容を解析できない場合、コールバックは空のオブジェクト {} を受け取ります。

現在のセッションの強制収集¶

setForcedSession() は現在のセッションを強制的に収集するために使用します。ローカルまたはリモートのサンプリングレートに該当しない場合でも、呼び出し後の 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() は呼び出し後のデータにのみ影響し、それ以前に破棄されたデータを補完することはありません。強制状態は現在のセッションにのみ有効で、セッションが期限切れになると最新のサンプリングレートに基づいて再計算されます。

セッションと実行時の動作¶

セッションは applicationId ごとに独立して保存され、異なる RUM アプリケーション間でセッション ID やサンプリング結果が再利用されることはありません。
15 分間連続してアクティビティがないと新しいセッションが作成されます。1 つのセッションの最長持続時間は 4 時間です。
ページへの進入、クリック、タッチ、入力、および宣言されたページスクロールによってセッションが延長されます。trackInteractions を無効にしても、自動 Action 収集が停止するだけで、セッションのアクティビティ認識には影響しません。
リモート設定が返される前のデータはローカル設定に従って処理され、遡って再計算されることはありません。
今回の初期化で新しく作成され、まだ強制サンプリングされていないセッションについては、リモートサンプリングレートが返された後にサンプリング結果を再計算できます。ストレージから復元されたセッションは、元のサンプリング決定が保持されます。
SDK が wx.request および wx.downloadFile をプロキシする場合、業務側の呼び出しの元の戻り値と Promise の動作は維持されます。