SDK配置使用指引
Bugly专业版支持在控制管理台，通过配置任务，控制SDK的行为。用户可以通过配置，控制监控功能的开启与否，控制是否允许上传自定义文件等等。本文主要介绍如何使用Bugly专业版的SDK配置。
一、概述
Bugly专业版支持丰富的配置能力，用户可以通过配置控制SDK的行为，如是否允许开启某个监控功能，是否允许上传自定义文件等等。在控制管理台，设置/SDK配置，即可体验相关功能。
产品刚创建时，配置任务列表为空，用户需要创建配置任务。除了新创建配置任务外，用户也可以对已有的配置任务进行修改。所有对配置进行的操作，会显示在配置修改历史中。
用户可以创建多个配置任务，为每个配置任务设置恰当的优先级以及过滤条件。当应用来拉取配置时，配置系统会根据配置请求中的参数，挑选出满足过滤条件的配置任务，在这些配置任务中找到优先最高的任务返回给应用。
过滤条件：描述一个配置任务要求来拉取的用户需要满足哪些特征。
优先级：描述当一个用户匹配到多个配置任务时，如何选择任务。当前是挑选优先级最高的任务。如果匹配的多个任务，优先级是一样的，则配置系统会随机选择一个任务返回。
如下图所示，BuglyProDemo包含多个配置任务，正式版的用户会拉取正式版配置(任务ID：56914)，而灰度版的用户则会拉取灰度配置(任务ID：56913)。如果应用初始化时，没有设置应用版本类型，则默认的应用版本类型为"Unknown"类型，用户会拉到默认配置(任务ID：56909)。
详细见本文中过滤条件/版本类型部分说明
如果产品绑定了「MAU包年套餐」，采样由平台控制，只允许用户关闭某个监控项，则配置的逻辑如下：
二、配置任务
一个配置任务包含任务名称（必填），过滤条件（默认表示不限制），优先级（必填），备注以及配置项组成。拉取配置时，先根据拉取的参数，根据任务的过滤条件，匹配满足条件的配置任务。如果同时匹配了多个配置任务，则根据任务的优先级，选择最高优先级的任务返回给SDK。如果匹配的多个配置任务，优先级是一样的，则由配置系统随机选择返回，不保证多次拉取时返回相同任务。优先级用数字表示，数字越大表示优先级越高。
如果没有命中任何配置任务，则配置系统会返回空配置。SDK拉到空配置后，会丢弃并且使用本地缓存的配置，有可能是上次拉取的配置，也有可能是默认配置。强烈建议业务创建一个优先级最低的，没有任何过滤条件的默认配置，保证应用在任何情况下都可以拉到一个配置任务。
1. 新建配置任务
用户可以点击新建配置，为对应的产品创建一个新的配置任务。配置任务创建成功后，默认状态是未开启的，需要用户主动开启。
2. 开启/关闭配置
用户可以直接操作配置状态，开启或者关闭配置任务。
应用拉取配置时，配置系统只取开启中的配置任务来进行匹配。未开启的配置任务不参与匹配，应用无法拉取到未开启的配置任务。如果用户想临时废弃某个配置任务，可以通过关闭该任务来实现。
3. 修改配置任务
无论是生效中的配置任务（已开启的配置任务），还是未生效的配置任务（未开启的配置任务），都支持编辑。
修改配置任务后，点击提交后，会显示本次修改的差异，用户点击提交，即真正提交本次修改。
4. 删除配置任务
无论是生效中的配置任务（已开启的配置任务），还是未生效的配置任务（未开启的配置任务），都支持删除。生效中的配置任务被删除后，应用下次拉取时，就不会再拉到被删除的配置任务。
5. 查看修改历史
配置修改历史记录了用户对配置任务执行的任何操作，包含新建配置任务，开启或者关闭配置任务，编辑配置任务以及删除配置任务。
支持查看某个配置任务的修改历史，如下示例，查看白名单配置的修改历史。也支持查看，某个用户的修改历史。
三、过滤条件
配置任务的默认过滤条件为空，即不限制拉取。用户可以为配置任务设置过滤条件，限制满足过滤条件的设备才能拉取。
当前配置任务支持的过滤条件包含如下，这些条件之间是全且关系，即同时满足多个条件即为满足当前配置任务的过滤条件。在配置任务列表中，展示当前任务的过滤条件。
1. 版本类型
版本类型，即应用版本类型，用来描述当前应用版本为开发版，还是灰度版，或者正式版，支持多选，默认不限制。应用没有设置的情况下，应用版本类型的默认值是未知类型，建议初始化SDK时，设置正确的应用版本类型。
通过BuglyBuilder#appVersionType初始化参数设置应用版本类型。
通过BuglyConfig#setBuildConfig接口设置应用版本类型。
示例：只有灰度版和正式版，才能拉取当前配置任务。
2. APP版本
APP版本，即应用版本，描述当前接入Bugly SDK的应用的版本号。
通过BuglyBuilder#appVersion初始化参数设置APP版本。
通过BuglyConfig#setAppVersion接口设置应用版本。
示例："4.5.6" 或者 "4.6.7" 才能拉取当前配置任务。
3. SDK版本
SDK版本指Bugly SDK的版本，不需要设置，对应接入时所依赖的SDK版本，支持多个，默认不限制。
示例：表示SDK版本是"4.3.0"或者"4.3.0.1"时，该条件满足。
4. 系统/系统版本
系统/系统版本指当前运行应用的操作系统的版本，不需要设置，SDK直接读取系统版本属性。系统版本支持设置多个，默认不限制。
SDK初始化时自动获取Build.VERSION.RELEASE字段，格式如"12","13","9","8.0.0"之类。
示例：表示系统版本是12，13，9，8.1，或者8.0.0时，系统版本的条件满足。
SDK初始化时自动获取 [[UIDevice currentDevice] systemVersion]字段，格式如"14.1","16.1"之类。
5. 机型
机型即设备类型，一般用来表示一种型号的设备。
通过BuglyBuilder#deviceModel初始化参数设置机型，如果应用没有设置，初始化时会自动读取Build.MODEL。
SDK初始化时自动获取 sysctlbyname字段，格式如"iPhone13,4","iPhone15,3"之类。
6. 用户白名单
通过BuglyBuilder#userId初始化参数设置用户ID，如果应用没有设置，则用户ID为空。
通过BuglyInitParam#setUserId接口设置用户ID。如果应用没有设置，则用户ID为空。
示例，用户ID为"marry", "mike"或者"jim"时，用户白名单条件满足。
7. 设备白名单
设备白名单对应SDK中的设备ID，支持设置多个，默认是不限制。
通过BuglyBuilder#uniqueId初始化参数设置设备ID，如果应用没有设置，SDK会优先从SP缓存中读取，如果缓存为空，则随机生成一个并且更新到缓存中。一旦用户设置设备ID，SDK会用应用设置的设备ID覆盖SP缓存。
通过BuglyInitParam#setDeviceId接口设置设备ID。如果应用没有设置，则设备ID为空。该字段用来统计设备崩溃率，设备FOOM率等设备异常率，请务必设置。
示例，设备ID为"b171a7113a0cfb05"，或者"2ee44f2a31f030a"时，设备白名单条件满足。
多条件组合示例，版本类型是开发版，且APP版本为"4.6.7"，且是Android 12的系统，则该配置任务满足条件。
四、配置项
Android和iOS平台，所支持的具体配置项有些差异，有关配置项的详细说明，请参考两端SDK的接入指引。除具体的配置项差异外，其他逻辑两端表现一致。
1. 设备采样率
绝大部分配置项有一个采样率（"sample_ratio"）参数，表示该监控能力的设备采样率。当前是后台采样，配置系统会根据来拉取配置的设备情况，通知SDK，当前设备是允许开启某个监控项，或者禁用某个监控项。1表示所有设备都允许开启某个监控项，0表示所有设备都不允许开启某个监控项。取(0,1)之间的某个值a，则表示按a指定的概率，部分设备允许开启某个监控项，部分设备不允许开启某个监控项。例如a=0.3，表示30%的设备允许开启指定监控项，70%的设备不允许开启指定监控项。
示例：允许所有的设备开启内存峰值监控，只允许10%的设备开启大图分析功能。
2. 关闭所有监控项
在不调整监控项的设备采样率（"sample_ratio"）的情况下，可以支持一键关闭所有的监控项。这个开关默认是false，用户打开后，所有命中该任务的设备，除崩溃等质量监控基础能力外，其他监控能力均被关闭。
当用户期望关闭所有监控项时，可以一项一项修改配置项的设备采样率（"sample_ratio"），也可以通过这个开关一键关闭所有的监控项。
3. Android配置项
- 崩溃、ANR、OOM是100%上报，不支持采样，默认开启。除崩溃、ANR、OOM外，其他监控项支持采样。一般情况下，性能指标监控默认开启，性能异常监控默认关闭，用户可以通过SDK配置调整开启情况。在接入时，请务必确认功能的开启情况符合你的预期。
一般情况下，性能指标监控默认开启，性能异常监控默认关闭。在接入时，请务必确认功能的开启情况符合你的预期。
需要在控制管理台的设置/SDK配置中，修改配置开关，指定监控项的采样率。
在接入期间，建议全采样，即将所有采样率调整为1.0，方便验证数据上报。接入完成后，再根据需要，调整采样率。
或者创建多个配置任务，根据版本类型（对应初始化的builder.appVersionType），配置开发任务，灰度任务，以及正式任务。开发任务打开所有的监控项，灰度阶段按需采样，正式发布根据需要降低采样。
各监控项的配置参数说明如下：
A.质量监控:
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 崩溃监控 | "crash" | "cus_file_sample_ratio" | 自定义文件的上报采样率，取值[0,1]，1表示全部上报，0表示不上报，其他表示抽样上报 |
| 错误上报 | "http" | "error_portal_ratio" | 错误的上报采样率，取值[0,1]，1表示全部上报，0表示不上报，其他表示抽样上报 |
B.启动监控:
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 启动监控 | "launch_metric" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
C.卡顿监控：
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 卡顿指标 | "looper_metric" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 卡顿监控 | "looper_stack" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 卡顿监控 | "looper_stack" | "event_sample_ratio" | 消息采样率, 取值[0,1]，1表示监控所有的UI线程消息，0表示不监控任何UI线程消息，其他表示指定概率，抽样监控UI线程的消息 |
| 卡顿监控 | "looper_stack" | "stack_interval_ms" | 卡顿抓栈间隔，单位是ms |
| 卡顿监控 | "looper_stack" | "threshold" | 判定卡顿的阈值，单位是ms |
D.内存监控
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 内存峰值 | "memory_quantile" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| Java内存泄露监控 | "activity_leak" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开Activity的泄露监控。 |
| Java内存泄露监控 | "activity_leak" | "event_sample_ratio" | 事件采样率，取值[0,1]，1表示Activity在onDestroy时，或者调用startInspectLeakObj时，全量开启Java对象泄露检查，0表示不开启Java对象泄露检查，其他表示按指定的概率抽样开启Java对象泄露检查。举例说明，取值0.5表示，Activity在onDestroy时或者调用startInspectLeakObj时，有50%的概率会开启Java对象泄露检查。 |
| 大图分析 | "big_bitmap" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 大图分析 | "big_bitmap" | "threshold" | 图片超标阈值，取值(100, Int最大值)，图片超标率 = Decode图片的长 x Decode图片的宽 / 显示区域的长 x 显示区域的宽 x 100。大图检测就是检查，Decode图片大小超过其显示区域大小的情况。例如，取值150表示，当图片超标率 > 150时，认为属于异常情况，需要上报。 |
| Native内存触顶监控 | "native_memory" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| Native内存触顶监控 | "native_memory" | "event_sample_ratio" | 事件采样率，取值[0,1]，用来控制，当发生内存触顶时(VSS或者PSS触顶)，dump内存进行数据上报的采样率 |
"activity_leak"的"sample_ratio"和"event_sample_ratio"的差异。
"sample_ratio"表示，允许多少比例的设备，监控Activity/Fragment的生命周期，在Activity执行onDestroy时，Fragment执行onFragmentDestroyed或者onFragmentViewDestroyed时调用startInspectLeakObj。
"event_sample_ratio"表示，当调用startInspectLeakObj时(无论是应用主动调用，还是监控自动调用)，按多大的概率来真正开启Java对象泄露的检测流程。
E.进程退出分析
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 进程退出分析 | "application_exit" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 进程退出分析 | "application_exit" | "event_sample_ratio" | 附件采样率, 取值[0,1]，表示当存在tombs附件或trace附件时，按指定概率抽样上报 |
F.流量监控
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 十分钟流量监控 | "traffic_detail" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 十分钟流量监控 | "traffic_detail" | "total_limit_in_megabyte" | 10分钟消耗的流量超过配置的流量异常阈值，单位是MB |
| 十分钟流量监控 | "traffic_detail" | "mobile_limit_in_megabyte" | 10分钟消耗的移动流量超过配置的移动异常流量阈值，单位是MB |
| 十分钟流量监控 | "traffic_detail" | "backend_limit_in_megabyte" | 在后台场景10分钟消耗的流量超过配置的后台异常流量阈值，单位是MB |
| 十分钟流量监控 | "traffic_detail" | "custom_limit_in_megabyte" | 业务定义的自定义场景，流量消耗是否超过定义的阈值，单位是MB |
| 流量监控 | "traffic" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
G.电量监控
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 电量指标监控 | "battery_metric" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 电量指标监控 | "battery_metric" | "daily_report_limit" | 监控项每天最大上报次数 |
| 耗电元素指标监控 | "battery_ele_metric" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 耗电元素指标监控 | "battery_ele_metric" | "daily_report_limit" | 监控项每天最大上报次数 |
| 耗电元素监控 | "battery_element" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 耗电元素监控 | "battery_element" | "daily_report_limit" | 监控项每天最大上报次数 |
| 耗电元素监控 | "battery_element" | "single_location_duration_in_ms" | 单次使用GPS最大时长，单位ms |
| 耗电元素监控 | "battery_element" | "total_location_duration_in_ms" | 10分钟内总的更新GPS时长，单位ms |
| 耗电元素监控 | "battery_element" | "max_location_open_num" | 10分钟内打开GPS的最大次数 |
| 耗电元素监控 | "battery_element" | "single_wakelock_duration_in_ms" | 单次使用WakeLock的最大时长，单位ms |
| 耗电元素监控 | "battery_element" | "total_wakelock_duration_in_ms" | 10分钟内总的使用WakeLock最大时长，单位ms |
| 耗电元素监控 | "battery_element" | "max_wakelock_open_num" | 10分钟内打开WakeLock的最大次数 |
| 耗电元素监控 | "battery_element" | "max_alarm_open_num" | 10分钟内打开alarm的最大次数 |
| 耗电元素监控 | "battery_element" | "max_wakeup_alarm_open_num" | 0分钟内打开wakeup 类型的alarm的最大次数 |
H.网络监控
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| 网络质量监控 | "net_quality" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 网络质量监控 | "net_quality" | "daily_report_limit" | 监控项每天最大上报次数 |
| 网络质量监控 | "net_quality" | "max_batch_count" | 一条上报最多包含请求明细条目 |
| 网络质量监控 | "net_quality" | "min_batch_count" | 一条上报最少包含请求明细条目 |
I.Asan内存错误检测
| 监控项 | 配置项 | 配置参数 | 取值说明 |
|---|---|---|---|
| ASan内存错误检测 | "asan" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| ASan内存错误检测 | "asan" | "slot_size" | 可分配内存Slot Page大小，单位KB，越大所需内存开销越大，建议使用默认值 |
| ASan内存错误检测 | "asan" | "slot_count" | 可分配内存Slot Page数量，数量越多会有更多的内存用于内存错误检测，内存开销越大，建议使用默认值 |
| ASan内存错误检测 | "asan" | "max_sample_gap_count" | 循环采样随机数的最大值，值越大内存分配时采样命中的概率越低 |
| ASan内存错误检测 | "asan" | "left_side_align_percentage" | 在ASan Memory Pool中内存分配时左对齐的概率，取值[0,100]，值越小越易于检测Overflow问题，反之越容易检测Underflow问题 |
| ASan内存错误检测 | "asan" | "right_side_perfect_align" | 在ASan Memory Pool中内存分配右对齐时是否不按页对齐，若不按页对齐更容易检测出Overflow问题，但也可能带来未知的crash风险 |
| ASan内存错误检测 | "asan" | "ignore_overlapped_reading" | 是否忽略重读类型的ASan错误 |
| ASan内存错误检测 | "asan" | "target_so_patterns" | 需要检测的SO文件，若为空默认检测全部SO，支持正则表达式设置，当内存问题能定位具体SO时，建议设置该值，可以减少稳定性问题 |
| ASan内存错误检测 | "asan" | "ignore_so_patterns" | 需要忽略的SO文件，若不为空默认不忽略任何SO，支持正则表达式设置 |
4. iOS配置项
崩溃是100%上报，不支持采样。除崩溃外，其他监控能力都支持采样，默认是全部关闭。
需要在控制管理台的设置/SDK配置中，修改配置开关，指定监控项的采样率。
在接入期间，建议全采样，即将所有采样率调整为1.0，方便验证数据上报。接入完成后，再根据需要，调整采样率。
或者创建多个配置任务，根据版本类型（对应初始化的buglyconfig.buildConfig），配置开发任务，灰度任务，以及正式任务。开发任务打开所有的监控项，灰度阶段按需采样，正式发布根据需要降低采样。
各监控项的配置参数说明如下：
| 监控项 | 配置项 | 支持的配置参数 | 取值说明 |
|---|---|---|---|
| 崩溃监控 | "crash.customfile" | "sample_ratio" | 自定义文件的上报采样率，取值[0,1]，1表示全部上报，0表示不上报，其他表示抽样上报 |
| 崩溃监控 | "crash.zombie" | "sample_ratio" | zomnbie检测的上报采样率，取值[0,1]，1表示全部上报，0表示不上报，其他表示抽样上报 |
| 启动监控 | "launch.launch" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 卡顿指标 | "looper.fluency" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 卡顿监控 | "looper.hitches" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| ANR监控 | "looper.deadlock" | "event_sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| 内存指标 | "memory.metric" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| FOOM监控 | "memory.foom" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
| VC内存泄露监控 | "memory.vc_leak" | "sample_ratio" | 设备采样率，取值[0,1]，1表示全部打开，0表示全部关闭，其他表示按指定概率抽样打开 |
五、MAU包年套餐配置控制
如果产品绑定了一个「MAU包年套餐」资源包，并且该资源包还在生效中，则产品的采样由平台控制，用户只能关闭某个监控项，其他的配置参数调整不生效。
如下图所示：配置系统按原逻辑匹配合适的配置任务，得到业务配置。在下发给SDK前，会进行配置合并。合并逻辑是，只有当业务配置中是关闭某个监控项时，合并后的配置也是关闭相关的监控项，否则只取「MAU包年套餐」指定配置。
示例如下，对于卡顿监控而言，取「MAU包年套餐」的指定配置。对于Java内存泄露而言，sample_ratio取匹配的业务配置，即取0（表示关闭监控项），其他配置参数取「MAU包年套餐」的指定配置。
示例中的「MAU包年套餐」指定配置仅作为示例，并非实际使用的配置。
