Skip to main content

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时,设置正确的应用版本类型。

Android SDK

通过BuglyBuilder#appVersionType初始化参数设置应用版本类型。

iOS SDK

通过BuglyConfig#setBuildConfig接口设置应用版本类型。

示例:只有灰度版和正式版,才能拉取当前配置任务。

应用版本类型

2. APP版本

APP版本,即应用版本,描述当前接入Bugly SDK的应用的版本号。

Android SDK

通过BuglyBuilder#appVersion初始化参数设置APP版本。

iOS SDK

通过BuglyConfig#setAppVersion接口设置应用版本。

示例:"4.5.6" 或者 "4.6.7" 才能拉取当前配置任务。

APP版本

3. SDK版本

SDK版本指Bugly SDK的版本,不需要设置,对应接入时所依赖的SDK版本,支持多个,默认不限制。

示例:表示SDK版本是"4.3.0"或者"4.3.0.1"时,该条件满足。

SDK版本

4. 系统/系统版本

系统/系统版本指当前运行应用的操作系统的版本,不需要设置,SDK直接读取系统版本属性。系统版本支持设置多个,默认不限制。

Android SDK

SDK初始化时自动获取Build.VERSION.RELEASE字段,格式如"12","13","9","8.0.0"之类。

示例:表示系统版本是12,13,9,8.1,或者8.0.0时,系统版本的条件满足。

系统

iOS SDK

SDK初始化时自动获取 [[UIDevice currentDevice] systemVersion]字段,格式如"14.1","16.1"之类。

5. 机型

机型即设备类型,一般用来表示一种型号的设备。

Android SDK

通过BuglyBuilder#deviceModel初始化参数设置机型,如果应用没有设置,初始化时会自动读取Build.MODEL

机型

iOS SDK

SDK初始化时自动获取 sysctlbyname字段,格式如"iPhone13,4","iPhone15,3"之类。

系统

6. 用户白名单

Android SDK

通过BuglyBuilder#userId初始化参数设置用户ID,如果应用没有设置,则用户ID为空。

iOS SDK

通过BuglyInitParam#setUserId接口设置用户ID。如果应用没有设置,则用户ID为空。

示例,用户ID为"marry", "mike"或者"jim"时,用户白名单条件满足。

用户白名单

7. 设备白名单

设备白名单对应SDK中的设备ID,支持设置多个,默认是不限制。

Android SDK

通过BuglyBuilder#uniqueId初始化参数设置设备ID,如果应用没有设置,SDK会优先从SP缓存中读取,如果缓存为空,则随机生成一个并且更新到缓存中。一旦用户设置设备ID,SDK会用应用设置的设备ID覆盖SP缓存。

iOS SDK

通过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数量
Java内存泄露监控配置说明

"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包年套餐」指定配置仅作为示例,并非实际使用的配置。

配置任务