You need to enable JavaScript to run this app.
导航

配置采样

最近更新时间2023.08.31 17:46:48

首次发布时间2023.04.20 16:46:09

有些场景下只希望上报部分数据,可以称为采样。本文介绍如何在SDK和平上中配置采样。

采样方式

在SDK插件中配置过滤

部分插件提供了一些过滤选项,可以针对简单的内容进行过滤,命中过滤则直接不上报。具体插件配置请参见配置插件
例如,JS错误插件提供了按照错误信息过滤的配置项。完成以下配置,可以不上报指定的符合条件的JS错误。

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    jsError: {
      ignoreErrors: ['Failed to fetch']
    }
  },
  ...
})

在beforeSend中过滤

SDK提供了多个生命周期,其中beforeSend是自定义采样时常用的生命周期,每一个需要上报的事件都会完成beforeSend生命周期。在回调里返回false、null或者undefined,就不会上报该事件到平台上。
例如,完成以下配置,当页面地址中包含test,该页面发生的JS错误就不上报。

import browserClient  from '@apmplus/web'
 
 browserClient('on', 'beforeSend', (ev) => {
    if(ev.ev_type === 'js_error' && ev.common.url.includes('test')) {
      return false // 不再上报
    }
    return ev // 继续上报
 })

ev的具体类型,除了查看ts提示,还可以查看@apmplus/web导出的类型BrowserSendEvent。

在SDK初始化时配置sample字段

您可以在init时传入sample对象来配置采样。

字段说明

字段

类型

说明

sample_rate

number

总采样率,对所有事件生效。

include_users

string[]

用户白名单,命中的用户会直接上报所有字段。

sample_granularity

string

采样模式。

  • session(默认):按照会话粒度采样。
  • event:按照事件粒度采样。

rules

{ [key: string]: EventSampleRule }

规则采样,针对不同事件类型来特殊配置,key为事件类型。

  • pageview
  • http
  • resource
  • ...

所有的插件名都是事件类型,如果您想查看事件类型的全部取值,请参见配置插件

sample_granularity说明

采样有两种模式:

  • session:按照会话粒度采样。
  • event:按照事件粒度采样。

例如,某个规则下的采样率是1%

  • session模式下,如果当前会话命中1%的采样率,那么会话下的所有符合规则的事件都会上报。
  • event模式下,每次事件都会重新计算是否命中1%的采样率,命中则上报,不命中则不被上报。

为了更好的还原单个用户下的所有行为,SDK默认采用的是session模式。

rules说明

rules常用于指定某个事件类型的特殊采样率或者特殊规则采样。rules的参数类型是对象格式,key对应插件名称,value对应的EventSampleRule类型。所有的插件名称,请查看配置插件
EventSampleRule的具体类型如下:

interface EventSampleRule {
  enable: boolean = true // 是否开启
  sample_rate: number = 1 // 采样率
  conditional_sample_rules?: Array<ConditionalSampleRule> // 条件采样规则
}

interface ConditionalSampleRule {
  sample_rate: number // 命中条件事件的采样率
  filter: FilterCondition // 命中过滤条件
}

interface FilterCondition {
  /** or 或者 and 或者rule */
  type: string // 'rule' | 'and' | or', rule 表示原子规则, and/or 表示对子规则的逻辑运算
  field?: string // 过滤判断的字段
  // op 代表匹配模式,包括 'eq' 等于 | 'neq' 不等于 | 'gt' 大于 | 'gte' 大于等于 |
  // 'lt' 小于 | 'lte' 小于等于 | 'regex' 正则符合 | 'not_regex' 正则不符合
  op?: string
  values?: Array<string> // 判断操作数,具体类型根据判断字段的类型以及操作符决定
  children?: Array<FilterCondition> // 子规则
}

您可以通过配置单个事件的sample_rate指定单个事件类型的采样率,也可以通过配置conditional_sample_rules指定不同规则下的采样率。
在conditional_sample_rules中,type用来指定多个子规则children之间的与和或关系,具体设计请参见举例说明

配置示例

场景一:总采样0.1,针对pageview事件再采样0.2。
pageview实际采样率 = 总采样 * 单一事件采样 = 0.1 * 0.2 = 0.02。

browserClient('init', {
  ...
  sample: {
    sample_rate: 0.1,
    include_users: [''],
    sample_granularity: 'session',
    rules: {
      pageview: {
        enable: true,
        sample_rate: 0.2,
        conditional_sample_rules: [],
      }
    },
  }
  ...
})

场景二:简单规则采样。
在场景一的基础上,设置一个条件,针对pid等于'login'的pageview事件只采样0.5。
[pid='login'] pageview实际采样率 = 总采样 * 规则采样率 = 0.05。

browserClient('init', {
  ...
  sample: {
    sample_rate: 0.1,
    include_users: [''],
    sample_granularity: 'session',
    rules: {
      pageview: {
        enable: true,
        sample_rate: 0.2,
        conditional_sample_rules: [
           {
             sample_rate: 0.5, 
             filter: { // 针对条件为payload.pid为 login 的 PV 上报
               type: 'rule',
               field: 'payload.pid',
               op: '=',
               values: ['login'],
             },
           },
        ],
      }
    },
  }
  ...
})

field的取值是BrowserSendEvent上报类型的字符串写法。在这个示例中,payload.pid等效于beforeSend中的ev.payload.pid。
场景三:复杂规则采样。
在上一个规则采样中再加入一个子规则。针对pid等于'login'并且release正则符合'0.1012'的pageview事件采样0.5。
pid等于'login'并且release正则符合'0.1012'的pageview实际采样率为 = 总采样 * 规则采样率= 0.05

browserClient('init', {
  ...
  sample: {
    sample_rate: 0.1,
    include_users: [''],
    sample_granularity: 'session',
    rules: {
      pageview: {
        enable: true,
        sample_rate: 0.2,
        conditional_sample_rules: [
          {
            sample_rate: 0.5, 
             filter: {
               type: 'and',
               children: [
                 {
                  type: 'rule',
                  field: 'payload.pid',
                  op: '=',
                  values: ['login'],
                 }, {
                   type: 'rule',
                   field: 'common.release',
                   op: 'regex',
                   values: ['0.1012'],
                 }
              ]
             },
          },
        ],
      }
    },
  }
  ...
})

如果配置了多个规则采样,会按照数组顺序进行配置,如果上一个规则命中,则使用对应规则的采样率,都否则命中下一个规则采样。
从使用的角度,虽然设计时有些复杂,但是足够灵活,可以满足任意场景。如果觉得手动配置太多复杂或者对正确配置没有把握,可以直接选择在平台上配置采样,平台和SDK使用的是同一套规则。

在平台上配置采样

平台侧可以在项目设置页面中配置采样率。
图片
相比于在SDK中使用sample来配置采样:

  • 平台配置的优点:
    • 无需发版,保存即生效,动态下发。
    • 更友好的交互,同时支持多层嵌套

      说明

      交互上支持多层嵌套,但是不推荐规则采样里再多层嵌套规则。

  • 平台配置的缺点
    • 由于采样的是setting下发的机制,所以可能存在setting偶尔请求失败的情况,可能会导致配置后依然存在零星上报的情况。

验证配置

您可以在network中过滤settings/get/webpro接口,从接口的响应体判断平台的配置是否有生效。
图片

配置优先级

如果SDK和平台都配置了采样,配置合并的优先级顺序为defaultConfig < ServerConfig < UserConfig。
同时合并规则为深度合并,即对象合并,数组也合并。