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. Android配置项
- 崩溃、ANR、OOM是100%上报,不支持采样,默认开启。除崩溃、ANR、OOM外,其他监控项支持采样。一般情况下,性能指标监控默认开启,性能异常监控默认关闭,用户可以通过SDK配置调整开启情况。在接入时,请务必确认功能的开启情况符合你的预期。
一般情况下,性能指标监控默认开启,性能异常监控默认关闭。在接入时,请务必确认功能的开启情况符合你的预期。
需要在控制管理台的设置/SDK配置中,修改配置开关,指定监控项的采样率。
在接入期间,建议全采样,即将所有采样率调整为1.0,方便验证数据上报。接入完成后,再根据需要,调整采样率。
或者创建多个配置任务,根据版本类型(对应初始化的builder.appVersionType),配置开发任务,灰度任务,以及正式任务。开发任务打开所有的监控项,灰度阶段按需采样,正式发布根据需要降低采样。
各监控项的配置参数说明如下:
A.质量监控:
监控项 | 配置项 | 配置参数 | 取值说明 |
---|---|---|---|
崩溃监控 | "crash" | "cus_file_sample_ratio" | 自定义文件的上报采样率,取值[0,1],1表示全部上报,0表示不上报,其他表示抽样上报,默认全部上报 |
错误上报 | "error_report" | "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 |
卡顿监控 | "looper_stack" | "detect_strategy" | 卡顿监控粒度,当前支持msg和vsync,默认是msg |
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对象泄露检查 |
Java内存触顶监控 | "java_memory_ceiling_hprof" | "sample_ratio" | 设备采样率,取值[0,1],1表示全部打开,0表示全部关闭,其他表示按指定概率抽样打开Java内存触顶监控 |
Java内存触顶监控 | "java_memory_ceiling_hprof" | "threshold" | 内存触顶阈值百分比,取值[0,100],表示达到Java最大可用内存的阈值百分比时,判定为内存触顶事件 |
Java内存触顶监控 | "java_memory_ceiling_hprof" | "event_sample_ratio" | 事件采样率,取值[0,1],用来控制,当发生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内存进行数据上报的采样率 |
FD触顶监控 | "fd_leak" | "sample_ratio" | 设备采样率,取值[0,1],1表示全部打开,0表示全部关闭,其他表示按指定概率抽样打开 |
FD触顶监控 | "fd_leak" | "event_sample_ratio" | 事件采样率,取值[0,1],用来控制,当发生FD触顶时,事件上报的概率 |
FD触顶监控 | "fd_leak" | "threshold" | 判定FD触顶的阈值,代表达到触顶的FD数量 |
"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" | 业务定义的自定义场景,10分钟消耗的流量超过配置的阈值,单位是MB |
流量异常分析 | "traffic_detail" | "filter_local_address" | 异常流量监控是否过滤本地地址,取布尔值 |
流量异常分析 | "traffic_detail" | "metric_event_sample_ratio" | 10分钟流量指标事件采样率,取值[0,1] |
流量异常分析 | "traffic_detail" | "error_event_sample_ratio" | 10分钟流量异常事件采样率,取值[0,1] |
流量指标 | "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,支持正则表达式设置 |
J.页面打开耗时
监控项 | 配置项 | 配置参数 | 取值说明 |
---|---|---|---|
页面打开耗时 | "page_launch" | "sample_ratio" | 设备采样率,取值[0,1],1表示全部打开,0表示全部关闭,其他表示按指定概率抽样打开 |
3. iOS配置项
崩溃是100%上报,不支持采样。除崩溃外,其他监控能力都支持采样,默认是全部关闭。
需要在控制管理台的设置/SDK配置中,修改配置开关,指定监控项的采样率。
在接入期间,建议全采样,即将所有采样率调整为1.0,方便验证数据上报。接入完成后,再根据需要,调整采样率。
或者创建多个配置任务,根据版本类型(对应初始化的buglyconfig.buildConfig),配置开发任务,灰度任务,以及正式任务。开发任务打开所有的监控项,灰度阶段按需采样,正式发布根据需要降低采样。
各监控项的配置参数参考 iOS 《SDK 功能配置项说明》。
五、MAU包年套餐配置控制
如果产品绑定了一个「MAU包年套餐」资源包,并且该资源包还在生效中,则产品的采样由平台控制,用户只能关闭某个监控项,其他的配置参数调整不生效。
如下图所示:配置系统按原逻辑匹配合适的配置任务,得到业务配置。在下发给SDK前,会进行配置合并。合并逻辑是,只有当业务配置中是关闭某个监控项时,合并后的配置也是关闭相关的监控项,否则只取「MAU包年套餐」指定配置。
示例如下,对于卡顿监控而言,取「MAU包年套餐」的指定配置。对于Java内存泄露而言,sample_ratio取匹配的业务配置,即取0(表示关闭监控项),其他配置参数取「MAU包年套餐」的指定配置。
示例中的「MAU包年套餐」指定配置仅作为示例,并非实际使用的配置。