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

采样方式

• 在SDK插件中配置过滤
  一般用于简单的采样需求。
• 在beforeSend中过滤
  常见的采样方式，使用简单，灵活性强。
• 在SDK初始化时配置sample字段
  常用于规则采样，可以指定任意事件和任意规则，配置任意的采样率。
• 在平台上配置采样
  同样可以指定任意事件和任意规则，配置任意的采样率，同时无需发版，动态下发。

在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_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和平台都配置了采样，配置合并的优先级顺序为：SDK默认配置 < 平台采样配置 < SDK初始化时用户传入的采样配置。
同时合并规则为深度合并，即对象合并，数组也合并。