文档中心

使用高阶功能

最近更新时间：2024.01.05 15:36:08

首次发布时间：2023.11.30 14:53:05

除了崩溃分析、错误分析、卡顿分析等常用的功能外，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;
    //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]方法结束启动链路。
示例代码：

#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;
}

自定义数据

使用如下接口，您可以添加一些自定义环境或业务信息，如用户email、定位信息、业务场景等，这些信息会随着SDK的日志一起上报，帮助您排查一些问题。

[RangersAPM setCustomContextValue:@"customKeyDemoTest" forKey:@"customValueDemoTest"];

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

自定义维度

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

[RangersAPM setCustomFilterValue:@"filterValueDemooTest" forKey:@"filterKeyDemoTest"];

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

注意

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

页面追踪

无需额外嵌码，引入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");
        }
    }];

全链路监控

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

//需要引入如下头文件
#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 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;
    }

注册崩溃后回调

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

// 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;

通知