文档中心

应用性能监控全链路版

iOS SDK 接入

使用高阶功能

除了崩溃分析、错误分析、卡顿分析等常用的功能外，SDK还支持一些增强功能。您可以根据业务需求，引入相应子库后使用这些功能。

通知

某些事件发生时，SDK会发出通知，您可以监听这些通知，来做一些自定义的应对措施。

以卡顿场景为例，您可以通过如下方式注册通知，如果引入了LAG子库，在卡顿场景发生时，SDK会发出通知，从而触发lagHandler。

说明

除了卡顿通知，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;
//business
NSTimeInterval 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]方法结束启动链路。

示例代码：

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的日志一起上报，帮助您排查一些问题。

添加成功后，您可以在控制台日志详情页面查看这些自定义数据。

自定义维度

使用如下接口，您可以添加一些自定义维度，作为自定义的的筛选项，用来筛选某些特定情况下的日志。

添加成功后，您可以在筛选列表中的自定义维度下查看这些自定义维度。

注意

在没有日志详情，只有统计数据的模块，无法看到这些自定义数据和自定义维度，如流畅性、HTTP等。

PV 自定义维度

使用如下接口，您可以添加一些作用于 PV 自定义维度，作为自定义的筛选项，用来筛选 PV 数据（目前 PV 数据在平台没有单独消费场景，常用于和崩溃、卡顿等数据结合计算崩溃率等）。

添加成功后，您可以在筛选列表中的 PV 自定义维度下查看这些数据。

注意

由于 PV 会在冷启动、热启动后立即上报，因此仅在冷启动 SDK 初始化时，或热启动应用进入前台之前，配置 PVFilters 才会对当次的 PV 数据生效。同时，我们也建议仅将一些非频繁变化的数据作为 PV 自定义维度，因为 PV 数据代表的是一个生命周期，生命周期内会变更的数据作为 PV 的维度会导致数据意义不明。

「自定义维度」和「PV 自定义维度」数据不互通，如果需要在其中添加相同的维度，请在客户端分别配置。

页面追踪

无需额外嵌码，引入UITrackers子库，就可以在崩溃详情页面现场数据页签下查看页面追踪，查看崩溃发生前用户的页面访问路径。卡顿详情也同样支持页面追踪。

连续崩溃保护

如果应用反复在启动后不久崩溃、卡死或 OOM，可以用连续崩溃保护在本地做一些处理，例如清理缓存、删除文件等。连续崩溃保护需要接入 SDK 的 BootingProtect 模块。

注意

bootingCrashHandler 不会在崩溃、卡死或 OOM 发生的当下回调，而是在异常退出后的下一次启动时触发：SDK 在启动阶段检测完上一次运行的异常后，在主线程执行该回调。如果需要在崩溃发生时记录信息，请使用"注册崩溃后回调"。

参数与行为说明：

bootingThreshold：启动崩溃阈值，单位为秒。只有从启动到发生异常的时长不超过该阈值时，才计为一次启动异常并触发回调；传 0 或负数表示不限时长。

上一次运行只要发生了符合条件的异常就会回调，第一次异常时 consecutiveExceptionTimes 即为 1。是否处理、连续多少次才处理，由业务在回调中根据次数自行判断。

上一次运行没有发生崩溃、卡死或 OOM 时，不会触发回调，所有计数清零。

回调在主线程执行。

必须在 [RangersAPM startWithConfig:] 之后调用，否则调用无效。同一个 AppID 只会注册一次，重复调用会被忽略。

统计 OOM 次数需要接入 BootingProtect 模块；只接入 BootingProtectLite 时不统计 OOM。

全链路监控

业务接入应用性能监控后，客户端进行如下配置，开启全链路监控。更多信息，请参见全链路监控。

获取设备数与用户数

客户端监控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 SDK

return YES;
}

配置SDK初始化config的deviceIDSource，应用性能监控全链路版会自动从RangersAppLog获取deviceID。

#import <RangersAPM.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

//初始化RangersAppLog

RangersAPMConfig *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;
}

注册崩溃后回调

注册崩溃后回调，可以在异常发生时进行回调，记录异常发生时的关键信息。

主动上报自定义日志

回捞自定义日志受限于用户行为，当收到用户反馈或者用户发生异常时，开发者可能无法及时获取到日志进行问题排查。

用户发生崩溃时的日志

配置方法：通过配置崩溃分析 > 是否上传自定义日志，让SDK上报崩溃日志的同时上报自定义日志，详情请参考SDK上报配置。

查看日志：在崩溃详情页面，选择自定义日志页签进行查看。

其他场景下，例如用户在APP内进行反馈，或者业务出错时，如果想要上报自定义日志协助问题排查，可以通过SDK提供的方法上报指定时间内的自定义日志。

配置方法：

/**
手动上报用户主动打点产生的自定义日志
@param fetchStartTime 需要上报的自定义日志的起始时间
@param fetchEndTime 需要上报的自定义日志的结束时间
@param callback 上传状态回调，isSuccess == YES 代表上传成功，fileCount 表示本次上报文件个数
*/
+ (void)reportALogWithFetchStartTime:(NSTimeInterval)fetchStartTime
fetchEndTime:(NSTimeInterval)fetchEndTime
callback:(void(^)(BOOL isSuccess, NSInteger fileCount))callback;

查看日志：主动上报的这部分数据，可以在自定义日志页面，输入DID进行查询，事件类型选择主动上报。

注意

自定义日志主动上报的量级不可控，且事件量消耗较大，建议修改自定义文件 > 主动上报自定义日志采样率。详情请参见SDK上报配置。

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)logType
fetchStartTime:(NSTimeInterval)fetchStartTime
fetchEndTime:(NSTimeInterval)fetchEndTime
detailCallback:(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 的计算公式为上述字段值的总和。

说明

阈值的默认值为 20 秒，如果想修改的话，可以参考SDK上报配置。

上报域名配置

说明

本配置适用于 RangersAPM >= 5.1.6

当应用内本产品SDK生产的数据只需要上报到单个公有云服务器时，按照应用接入iOS SDK的流程接入即可。如果需要配置数据上报到私有云服务器，或者需要集成多个公有云上报域名、并通过初始化参数控制实际上报服务器时，可以参考如下内容

Subspec 介绍

Subspec 名称	服务器地址	适用场景
CN	北京	中国大陆（不包括港澳台地区）发布的应用
Global	柔佛	海外发布的应用

初始化参数介绍

这个初始化参数用来实现一些特殊的上报配置，建议先阅读如下说明理解不同配置项的含义后，在根据自己的应用场景进行配置

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; //这一行也可以不用加，默认就是 RangersAPMDomainTypeSingle
config.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

最近更新时间：2026.10.15 20:24:46

这个页面对您有帮助吗？

有用

无用