应用性能监控全链路版
应用性能监控全链路版
文档指南
请输入
- 文档首页
应用性能监控全链路版用户指南客户端监控App 端监控SDK 接入iOS SDK 接入使用高阶功能
复制全文
下载 pdf使用高阶功能
文档反馈
问问助手除了崩溃分析、错误分析、卡顿分析等常用的功能外，SDK还支持一些增强功能。您可以根据业务需求，引入相应子库后使用这些功能。
通知
某些事件发生时，SDK会发出通知，您可以监听这些通知，来做一些自定义的应对措施。
以卡顿场景为例，您可以通过如下方式注册通知，如果引入了LAG子库，在卡顿场景发生时，SDK会发出通知，从而触发lagHandler。
#import <RangersAPMNotifications.h>
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(lagHandler) name:APMLagTimeOutNotification object:nil];
说明
- 除了卡顿通知，SDK还支持内存触顶等其他通知，详情可以查看头文件RangersAPMNotifications.h。
- SDK版本需大于1.5.4。
启动分析时间校准
默认监控的启动阶段
启动分析默认监控四个启动阶段：
- from_exec_to_load
- from_load_to_didFinishLaunching
- from_didFinishLaunching_to_first_render_time
- from_vc_loadView_to_didAppear
各阶段时间节点说明：
时间节点 | 说明 |
exec | APP进程启动的时间 |
load | RangersAPM的+load调用时间 |
didFinishLaunching | 初始化RangersAPM的时间 |
first_render_time | 第一次CoreAnimation提交的时间 |
vc_loadView | 第一个ViewController，loadView的时间 |
didAppear | 第一个ViewController，viewDidAppear的时间 |
自定义埋点
如果需要额外记录启动过程的某些节点，请参考如下两种埋点方案。
注意
以下两个埋点方法，只能在App启动阶段进行埋点，APP启动完成后调用是无效的。
- 在节点开始和结束分别埋点
- #import <RangersAPM+PerformanceAPI.h>RangersAPMConfig *config = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];[RangersAPM startWithConfig:config];[RangersAPM beginLaunchSpan:@"business" callback:^(NSError * _Nullable error) {if (error.code == RangersAPMStartDetectorErrorTypeDuplicateSpanName) {//do something}}];//business[RangersAPM endLaunchSpan:@"business" callback:^(NSError * _Nullable error) {if (error.code == RangersAPMStartDetectorErrorTypeDuplicateSpanName) {//do something}}];
- 记录节点开始时间和结束时间，在节点结束时埋点
- #import <RangersAPM+PerformanceAPI.h>RangersAPMConfig *config = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];[RangersAPM startWithConfig:config];NSTimeInterval startTime = [[NSDate date] timeIntervalSince1970] * 1000;//businessNSTimeInterval endTime = [[NSDate date] timeIntervalSince1970] * 1000;[RangersAPM addSpan:@"business" startTimeMs:startTime endTimeMs:endTime callback:^(NSError * _Nullable error) {if (error.code == RangersAPMStartDetectorErrorTypeDuplicateSpanName) {//do something}}];
自定义终点
如果您想要自定义启动链路的终点，需要配置RangersAPMConfig的customFinishStartTrace参数为YES，并在SDK初始化之后，即[RangersAPM startWithConfig:]之后，在一个合适的时机调用[RangersAPM finishLaunchTrace]方法结束启动链路。
示例代码：
#import <RangersAPM.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
RangersAPMConfig *apmConfig = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];
apmConfig.customFinishStartTrace = YES;
apmConfig.channel = @"App Store";
[RangersAPM startWithConfig:apmConfig];
[RangersAPM finishLaunchTrace];
return YES;
}
iOS Prewarm
iOS 15以上的系统中存在Prewarm策略，使得应用的一部分启动流程提前，导致平台统计到的启动时间偏大。
对于这种情况，平台采取方案：如果触发了Prewarm，那么平台统计到的启动时长会进行校准，即忽略一部分启动时间，因此统计到的启动时间会略小于真实时间，且上报的启动Trace可能会缺少execToLoad或者loadToDidFinishLaunching时间。
如果您希望获取更加精准的启动时间，请把SDK升级到2.11.1或更高版本，并执行以下操作：在main方法中调用[RangersAPM prewarmCheckStart]，同时在application:willFinishLaunchingWithOptions:方法中调用[RangersAPM prewarmCheckEnd]。如果您的main方法或者application:willFinishLaunchingWithOptions:方法中包含复杂逻辑，则不建议此操作。
延迟初始化
注意
该方法用于获取应用启动阶段关键点的时间戳，不涉及个人信息，如果需要在用户确认隐私弹窗之前调用此方法，请您结合自身应用的合规要求确认是否允许SDK在初始化之前执行代码逻辑。
我们建议在application:didFinishLaunchingWithOptions:最开始启动 SDK，以获取较为准确的启动时间。如果由于特殊原因无法太早启动，请首先在application:didFinishLaunchingWithOptions:调用[RangersAPM applicationDidFinishLaunching]。
自定义数据
使用如下接口，您可以添加一些自定义环境或业务信息，如用户email、定位信息、业务场景等，这些信息会随着SDK的日志一起上报，帮助您排查一些问题。
[RangersAPM setCustomContextValue:@"customKeyDemoTest" forKey:@"customValueDemoTest"];
添加成功后，您可以在控制台日志详情页面查看这些自定义数据。
自定义维度
使用如下接口，您可以添加一些自定义维度，作为自定义的的筛选项，用来筛选某些特定情况下的日志。
[RangersAPM setCustomFilterValue:@"filterValueDemooTest" forKey:@"filterKeyDemoTest"];
添加成功后，您可以在筛选列表中的自定义维度下查看这些自定义维度。
注意
在没有日志详情，只有统计数据的模块，无法看到这些自定义数据和自定义维度，如流畅性、HTTP等。
PV 自定义维度
使用如下接口，您可以添加一些作用于 PV 自定义维度，作为自定义的筛选项，用来筛选 PV 数据（目前 PV 数据在平台没有单独消费场景，常用于和崩溃、卡顿等数据结合计算崩溃率等）。
RangersAPMConfig *apmConfig = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];
apmConfig.PVFilters = @{@"key1": @"value1"};
[RangersAPM startWithConfig:apmConfig];
添加成功后，您可以在筛选列表中的 PV 自定义维度下查看这些数据。
注意
- 由于 PV 会在冷启动、热启动后立即上报，因此仅在冷启动 SDK 初始化时，或热启动应用进入前台之前，配置 PVFilters 才会对当次的 PV 数据生效。同时，我们也建议仅将一些非频繁变化的数据作为 PV 自定义维度，因为 PV 数据代表的是一个生命周期，生命周期内会变更的数据作为 PV 的维度会导致数据意义不明。
- 「自定义维度」和 「PV 自定义维度」数据不互通，如果需要在其中添加相同的维度，请在客户端分别配置。
页面追踪
无需额外嵌码，引入UITrackers子库，就可以在崩溃详情页面现场数据页签下查看页面追踪，查看崩溃发生前用户的页面访问路径。卡顿详情也同样支持页面追踪。
连续崩溃保护
连续崩溃保护可以在应用发生连续的崩溃时进行一些本地的处理，例如清理缓存、删除文件等。连续崩溃保护需要接入SDK的BootingProtect模块。
#import <RangersAPM+BootingProtect.h>
[RangersAPM startProtectWithBootingThreshold:10 bootingCrashHandler:^(RangersAPMBootingInfo * _Nonnull info) {
/**
对连续异常的场景进行防护策略，这里的demo只输出了一些log，您可以在自己的应用中做一些本地缓存清理或其他策略。可以针对不同的异常发生次数制定不同的策略。
*/
if (info.consecutiveExceptionTimes >= 1) {
NSLog(@"⚠️Consecutive exception 1 time");
} else if (info.consecutiveExceptionTimes >= 3) {
NSAssert(NO, @"⚠️Consecutive exception 3 times !!!");
}
/**
除了对连续异常进行防护，您也可以针对不同的异常类型执行不同的防护策略。
*/
if (info.crashTimes >= 1) {
NSLog(@"⚠️Consecutive crash 1 time");
}
if (info.watchdogTimes >= 1) {
NSLog(@"⚠️Consecutive watchdog 1 time");
}
if (info.OOMTimes >= 1) {
NSLog(@"⚠️Consecutive oom 1 time");
}
}];
全链路监控
//需要引入如下头文件
#import <RangersAPMConfig+NetworkPro.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
RangersAPMConfig *apmConfig = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];
apmConfig.channel = @"App Store";
//配置 enableTracing 为 YES 以开启全链路监控功能
apmConfig.enableTracing = YES;
[RangersAPM startWithConfig:apmConfig];
return YES;
}
获取设备数与用户数
应用性能监控全链路版SDK内部默认使用自身服务生成的DeviceID来标识一台设备和用户。
如果您不想使用SDK自身服务生成的DeviceID，可以参考下文的其他方案。如果您选择使用其他方案，SDK内部就不会再次请求自身服务生成DeviceID。
使用RangersAppLog生成的DeviceID
如果您想要或者已经接入了RangersAppLog，请执行以下步骤获取设备数。
- 在Podfile中声明RangersAppLog依赖，RangersAppLog版本需要大于6.0.1。
- pod 'RangersAppLog', '>=6.0.1', :subspecs => ['Core','Host/CN']
- 初始化RangersAppLog SDK。
- #import <BDAutoTrack.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {BDAutoTrackConfig *config = [BDAutoTrackConfig configWithAppID:@"{{app_id}}" launchOptions:launchOptions];config.channel = @"App Store";[BDAutoTrack startTrackWithConfig:config];//初始化APMPlus SDKreturn YES;}
- 配置SDK初始化config的deviceIDSource，应用性能监控全链路版会自动从RangersAppLog获取deviceID。
- #import <RangersAPM.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {//初始化RangersAppLogRangersAPMConfig *apmConfig = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];apmConfig.channel = @"App Store";apmConfig.deviceIDSource = RAPMDeviceIDSourceFromRAppLog;[RangersAPM startWithConfig:apmConfig];return YES;}
使用自己的DeviceID
如果您想使用自己的deviceID，请严格执行以下步骤获取设备数。
- 配置应用性能监控全链路版SDK初始化config的deviceIDSource。
- 在应用性能监控全链路版SDK初始化方法调用之后，再设置deviceID。
- #import <RangersAPM.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {RangersAPMConfig *apmConfig = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];apmConfig.channel = @"App Store";apmConfig.deviceIDSource = RAPMDeviceIDSourceFromUser;[RangersAPM startWithConfig:apmConfig];[RangersAPM setDeviceID:@"MYDEVICEID"];return YES;}
注册崩溃后回调
注册崩溃后回调，可以在异常发生时进行回调，记录异常发生时的关键信息。
// RangersAPM+CrashCallback.h
/**
RangersAPM 内部处理完 Crash 后，回调业务方，自定义数据，会在 APMInsight平台 自定义数据中展示
⚠️⚠️⚠️ Warning ⚠️⚠️⚠️
⚠️⚠️⚠️ Crash后App运行环境比较脆弱，容易造成二次Crash或死锁，除非非常必要，否则不建议使用该方法 ⚠️⚠️⚠️
业务方收到回调时，表明App已发生Crash，运行在异常环境，所以存在使用限制，应该遵守下面约定：
1. 回调方法内部应该越简单越好，只用于记录关键信息，尽快结束 （Crash期间用户端表现为界面卡死状态）
2. 这时除了当前线程，其他线程都被挂起，所以不要开启其他线程
3. 不要调用OC方法，容易造成死锁
4. 尽量不要在堆上malloc分配内存
*/
@interface RangersAPM (CrashCallback)
+ (void)registerCallback:(apm_crash_callback)callback;
+ (void)removeCallback:(apm_crash_callback)callback;
主动上报自定义日志
回捞自定义日志受限于用户行为，当收到用户反馈或者用户发生异常时，开发者可能无法及时获取到日志进行问题排查。
- 用户发生崩溃时的日志
- 配置方法：通过配置崩溃分析 > 是否上传自定义日志，让SDK上报崩溃日志的同时上报自定义日志，详情请参考SDK上报配置。
- 查看日志：在崩溃详情页面，选择自定义日志页签进行查看。
-
- 其他场景下，例如用户在APP内进行反馈，或者业务出错时，如果想要上报自定义日志协助问题排查，可以通过SDK提供的方法上报指定时间内的自定义日志。
- 配置方法：
- /**手动上报用户主动打点产生的自定义日志@param fetchStartTime 需要上报的自定义日志的起始时间@param fetchEndTime 需要上报的自定义日志的结束时间@param callback 上传状态回调，isSuccess == YES 代表上传成功，fileCount 表示本次上报文件个数*/+ (void)reportALogWithFetchStartTime:(NSTimeInterval)fetchStartTimefetchEndTime:(NSTimeInterval)fetchEndTimecallback:(void(^)(BOOL isSuccess, NSInteger fileCount))callback;
- 查看日志：主动上报的这部分数据，可以在自定义日志页面，输入DID进行查询，事件类型选择主动上报。
-
注意
APMPlus日志
考虑到成本和性能，APMPlus的一些功能的上报策略是采样上报，这样一来，当需要单点排查某个用户发生的问题时，由于没有全部的功能日志，会对问题的排查造成不便。为了解决这种问题，SDK支持把部分功能日志以自定义日志的形式写入，但不上报单独的功能日志，便于需要排查问题时进行回捞或者主动上报。
前提条件
- SDK升级到3.10.4或更高版本。
- 已配置自定义日志，详情请参见日志回捞。
- 已配置APMPlus日志采样率，详情请参见SDK上报配置。
- 新建APMPlus日志回捞任务，详情请参见新建日志回捞任务。
主动上报
- 用户发生崩溃前的日志
- 配置方法：通过配置崩溃分析 > APMPlus日志崩溃上报采样率，让SDK上报崩溃日志的同时上报APMPlus日志，详情请参见SDK上报配置。
- 查看日志：在崩溃详情页面，选择自定义日志页签进行查看。
-
- 其他场景下，例如用户在APP内进行反馈，或者业务出错时，如果想要上报APMPlus日志协助问题排查，可以通过SDK提供的方法上报指定时间内的APMPlus日志。
说明
如果希望同时上报用户自定义日志和APMPlus日志，logType参数可以这样传递：
[RangersAPM reportALogOfType:(RangersAPMALogTypeCustom | RangersAPMALogTypeMonitor) ...]
- 配置方法：
- typedef NS_OPTIONS(NSUInteger, RangersAPMALogType) {RangersAPMALogTypeCustom = 1<<0, //用户主动打点RangersAPMALogTypeMonitor = 1<<1 //SDK 内置打点};/**手动上报多类型自定义日志@param logType 需要上报的日志类型，同时上报多种类型示例：RangersAPMALogTypeCustom | RangersAPMALogTypeMonitor@param fetchStartTime 需要上报的自定义日志的起始时间@param fetchEndTime 需要上报的自定义日志的结束时间@param detailCallback 上传状态回调，如果同时上报多种类型，回调可能执行多次，logType 标识本次回调上报的类型，isSuccess == YES 代表本次回调上传成功，fileCount 表示本次回调上报文件个数*/+ (void)reportALogOfType:(RangersAPMALogType)logTypefetchStartTime:(NSTimeInterval)fetchStartTimefetchEndTime:(NSTimeInterval)fetchEndTimedetailCallback:(void(^)(RangersAPMALogType logType, BOOL isSuccess, NSInteger fileCount))detailCallback;
- 查看日志：主动上报的这部分数据，可以在自定义日志页面，输入DID进行查询，事件类型选择主动上报。
-
页面体验异常数据治理
在 5.1.2 版本以前，页面体验支持如下阶段：
- loadView：loadView 的时间消耗
- viewDidLoad：viewDidLoad 的时间消耗
- viewWillAppear：viewWillAppear 的时间消耗
- viewDidAppear：viewDidAppear 的时间消耗
- methodsTotalTime：viewDidAppear 的结束时间 - loadView 的开始时间
当控制器的创建和展示分散时，就会造成数据异常，尤其是 methodsTotalTime 数据会异常巨大，对整体指标产生影响。
为了兼容这个问题，我们在 5.1.2 版本中，兼容如下逻辑：
- loadView_to_viewDidLoad：viewDidLoad 的开始时间 - loadView 的结束时间
- viewDidLoad_to_viewWillAppear：viewWillAppear 的开始时间 - viewDidLoad 的结束时间
- viewWillAppear_to_viewDidAppear：viewDidAppear 的开始时间 - viewWillAppear 的结束时间
同时，为了防止控制器的创建和展示分散的情况，对上述时间增加阈值限定。这个阈值对上述三个时间单独生效，哪个时间超过阈值，就会抛弃哪一个时间值。另外，调整 methodsTotalTime 的计算公式为上述字段值的总和。
说明
上报域名配置
说明
本配置适用于 RangersAPM >= 5.1.6
当应用内本产品SDK生产的数据只需要上报到单个公有云服务器时，按照应用接入iOS SDK的流程接入即可。如果需要配置数据上报到私有云服务器，或者需要集成多个公有云上报域名、并通过初始化参数控制实际上报服务器时，可以参考如下内容
Subspec 介绍
初始化参数介绍
这个初始化参数用来实现一些特殊的上报配置，建议先阅读如下说明理解不同配置项的含义后，在根据自己的应用场景进行配置
/**
The domain type SDK should choose.
*/
typedef enum {
/**
Only one of the domian subspecs should be involved.
*/
RangersAPMDomainTypeSingle,
/**
No need for any domain subspec.
⚠️ You must set config.domain as your own host which is necessary to avoid exceptions.
*/
RangersAPMDomainTypePrivate,
/**
Muiltiple domain subspecs can be involved, and use CN.
⚠️ The config.domain you set will be ignored.
*/
RangersAPMDomainTypeCN,
/**
Muiltiple domain subspecs can be involved, and use Global.
⚠️ The config.domain you set will be ignored.
*/
RangersAPMDomainTypeGlobal
} RangersAPMDomainType;
- RangersAPMDomainTypeSingle：默认值。必须且只能引入一个包含上报域名的 subspec，并且会使用该 subspec 中的上报域名上报数据，例如上报到国内的公有云服务器需要接入 CN。
- RangersAPMDomainTypePrivate：上报到私有云服务器。引入的任何 subspec 的上报域名均不会被使用，只会使用初始化配置的私有云服务器地址，当初始化配置的私有云服务器地址为空时，数据上报会失败。RangersAPMDomainTypeSingle 也可以在初始化时配置私有云服务器地址，但是当初始化配置的私有云服务器地址为空时，会使用引入的 subspec 中的上报域名。
- RangersAPMDomainTypeCN：上报到公有云服务器-CN。可以引入多个包含上报域名的 subspec，但只有 CN 中的上报域名会被使用，如果没有引入 CN，则数据上报会失败。
- RangersAPMDomainTypeGlobal：上报到公有云服务器-Global。可以引入多个包含上报域名的 subspec，但只有 Global 中的上报域名会被使用，如果没有引入 Global，则数据上报会失败。
上报到私有云服务
本节介绍如何将数据上报到私有云服务，有两种方案
- 方案一：RangersAPMDomainTypeSingle
- 接入一个包含上报域名的 subspec，当初始化配置的 domain 为空时，会使用 subspec 中的域名兜底
- 初始化时配置 RangersAPMConfig.domainType 和 RangersAPMConfig.domain
- #import <RangersAPM.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {RangersAPMConfig *config = [RangersAPMConfig configWithAppID:@"app_id" appToken:@"app_token"]; //需要把这里的 app_id 和 app_token 替换为您自己的应用信息config.domainType = RangersAPMDomainTypeSingle; //这一行也可以不用加，默认就是 RangersAPMDomainTypeSingleconfig.domain = @"domain"; //需要把这里替换成私有云服务器地址，如果配置的 domain 不包含 protocol，则默认使用 https://... //这里可以根据需要添加其他配置[RangersAPM startWithConfig:config];return YES;}
- 方案二：RangersAPMDomainTypePrivate
- 不需要接入任何包含上报域名的 subspec，即使接入了也不会使用，当初始化配置的 domain 为空时，会上报失败
- 初始化时配置 RangersAPMConfig.domainType 和 RangersAPMConfig.domain
- #import <RangersAPM.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {RangersAPMConfig *config = [RangersAPMConfig configWithAppID:@"app_id" appToken:@"app_token"]; //需要把这里的 app_id 和 app_token 替换为您自己的应用信息config.domainType = RangersAPMDomainTypePrivate;config.domain = @"domain"; //需要把这里替换成私有云服务器地址，如果配置的 domain 不包含 protocol，则默认使用 https://... //这里可以根据需要添加其他配置[RangersAPM startWithConfig:config];return YES;}
集成多个公有云上报域名
警告
如您订购华北区和柔佛区服务，我们建议您在您国内发布的应用包内集成CN公有云上报域名，在海外发布的应用包内集成Global公有云上报域名。如您希望在同一个应用包内集成多个区域公有云上报域名，您需自行评估和判断法律合规风险，避免因为数据上报地域不符合当地法律规定而造成损失。
本节介绍如何集成多个公有云上报域名，并通过初始化参数配置实际的上报地址。适用于同一个应用包，同时提供给国内和海外用户使用的场景，并根据下载渠道将本 SDK 生产的数据上报到不同的服务器。
- 接入需要的 subspec
- 初始化时配置 RangersAPMConfig.domainType
#import <RangersAPM.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
RangersAPMConfig *config = [RangersAPMConfig configWithAppID:@"app_id" appToken:@"app_token"]; //需要把这里的 app_id 和 app_token 替换为您自己的应用信息
config.domainType = RangersAPMDomainTypeCN; //根据需要配置不同的 domainType
... //这里可以根据需要添加其他配置
[RangersAPM startWithConfig:config];
return YES;
}
最近更新时间：2026.02.10 19:56:26
这个页面对您有帮助吗？
有用
有用
无用
无用