验证数据上报

您可以根据业务需要，按照以下各模块说明，检查对应模块是否接入成功。

前提条件

完成SDK上报配置

• 配置设备白名单
  SDK上报配置页面默认配置的采样率较低，在SDK接入测试阶段请配置DID白名单，确保当前设备所有性能数据都采样命中，才能上报到平台查看这些数据。具体请参见创建白名单和如何获取DID？。
• 配置各模块采样率
  崩溃是100%上报的，不受采样率控制。除了崩溃，其他监控数据需要在SDK上报配置页面配置采样上报，默认情况下采样命中后才会上报。
  例如，验证卡顿数据前，请在SDK上报配置页面打开总开关，并将卡顿采样率配置为100%。验证完成后，再修改为适合的采样率。具体请参见创建SDK上报配置。

开启Debug日志

开启Debug日志输出功能，SDK就会在初始化成功、上报成功等关键时刻，向Xcode控制台输出日志，帮助您对SDK的接入和上报进行验证。
示例代码：

#import <RangersAPM+DebugLog.h>

#if DEBUG
                //通过修改block，您可以定制自己的日志输出格式，下述代码示例是SDK内部默认的输出格式，如果您传入nil，则SDK会使用默认的格式输出日志。
    [RangersAPM allowDebugLogUsingLogger:^(NSString * _Nonnull log) {
        NSLog(@"APMPlus : %@", log);
    }];
#endif

                //请先于此代码开启debug日志，否则对于一些同步事件可能无法输出日志
    [RangersAPM startWithConfig:config];

日志输入说明：

崩溃分析

完整的崩溃分析功能需要引入子库，包括Crash、WatchDog、OOM，支持单独引入各个子库。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。

1. 添加以下代码到App代码中，触发NSException类型的Crash。

   dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(5 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
           NSArray *array = [NSArray array];
           [array objectAtIndex:10];
       });
   

2. 在Xcode中，修改Build Configuration为Release，然后通过Run把App安装到模拟器或者真机。

3. 在模拟器或者真机中打开App，然后等待崩溃代码执行，App闪退。

   注意

   不要直接通过Xcode Run启动App，这样触发的崩溃无法捕获。

4. 在Xcode中，通过Run重新启动App，SDK会立即上报上一次启动期间发生的崩溃，然后在控制台看到上报成功的日志。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

错误分析

错误分析模块分为自定义错误和网络错误。

• 自定义错误模块：需要引入子库UserException。
  自定义错误是自埋点功能，需要手动调用接口来记录App发生的错误，并上报到应用性能监控全链路版平台，统一查看。
• 网络错误模块：需要引入子库Network。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
以下示例代码会记录1条自定义错误日志，SDK每记录5条日志会触发一次上报。网络错误日志可以通过发送一次会发生错误的网络请求来自动记录。

#import <RangersAPM+UserException.h>

[RangersAPM trackAllThreadsLogExceptionType:@"testUserException" 
                               skippedDepth:0  
                             customParams:@{@"testCustomKey":@"testCustomValue"}
                                  filters:@{@"testFilterKey":@"testFilterValue"}
                                 callback:^(NSError * _Nullable error){
                                    NSLog(@"%@",error); 
                                 }
];

如果安装SDK时，无法找到以上头文件及接口，请检查SDK的版本，将其升级至1.1.0以上，或者参考以下代码记录自定义错误。

#import <RangersAPMUserExceptionManager.h>
            
    [RangersAPMUserExceptionManager trackAllThreadsLogExceptionType:@"testUserException" 
                       skippedDepth:0 
                       customParams:@{@"testCustomKey":@"testCustomValue"} 
                            filters:@{@"testFilterKey":@"testFilterValue"}
                           callback:^(NSError * _Nullable error) {
                                 NSLog(@"%@",error);}
    ];

上报策略

网络错误日志记录后不会立即上报，在以下时间会自动上报：

• App启动15s之后，触发一次上报。
• 每经过60s，触发一次上报。
• 当App状态切换到background时，触发一次上报。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

卡顿分析

卡顿分析模块需要引入子库LAG。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
通过阻塞主线程来模拟一个卡顿事件。阻塞时间需要大于您在SDK上报配置中配置的卡顿阈值，才能被SDK捕获上报。如果未修改卡顿阈值，默认阈值为2.5s。

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(5 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    sleep(5);
});

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

事件分析

事件分析模块是自埋点功能，需要您手动调用接口来进行事件的记录，使用该功能需要引入EventMonitor模块。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
以下示例代码可以记录一个事件，相关参数可以查看头文件介绍。

#import "RangersAPM+EventMonitor.h"
  
  [RangersAPM trackEvent:@"event_name1"
          metrics:@{@"metric1":@(0)}
         dimension:@{@"dimension1":@"test"}//Metrics参数只支持Key为NSString类型，Value为NSNumber类型的NSDictionary对象。Metrics参数不支持嵌套结构。
        extraValue:@{@"extra1":@"extravalue"}];//dimension参数只支持Key和Value都为NSString类型的NSDictionary对象。dimension参数不支持嵌套结构。

上报策略

事件记录后不会立即上报，客户端上报规则如下：

• App启动之后，触发一次上报。
• 每经过60s，触发一次上报。
• 当App状态切换到background时，触发一次上报。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

用户体验

用户体验模块分为启动分析、页面响应分析、流畅性分析。

• 启动分析模块：需要引入子库Monitors。
• 流畅性分析模块：需要引入子库Monitors。
• 页面响应分析模块：需要引入子库UITrackers。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
用户体验模块日志会在App的状态或者场景发生变化时进行记录，触发方式如下：

• 启动分析
  • App启动时会记录冷启动日志，该日志不可手动触发，且对于App的每次启动只会记录一条冷启动日志。
  • App从后台切换到前台会记录热启动日志，可以通过前后台切换来进行触发。
• 页面响应日志
  当App发生场景切换时会记录页面响应日志，日志包含如下阶段的耗时：loadView、viewDidLoad、viewWillAppear、viewDidAppear，可以通过切换viewController来触发。

上报策略

用户体验日志记录后不会立即上报，在以下时间会自动上报：

• App启动15s之后，触发一次上报。
• 每经过60s，触发一次上报。
• 当App状态切换到background时，触发一次上报。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

页面监控

页面监控模块会捕获App的WebView发生的加载、请求和错误事件，开启功能需要引入子库Hybrid。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
您可以使用Web Demo在您的App中新建WebView进行测试，也可以参考Demo在您的App原本的WebView页面中编写测试用例。

上报策略

页面监控日志记录后不会立即上报，在以下时间会自动上报：

• App启动15s之后，触发一次上报。
• 每经过60s，触发一次上报。
• 当App状态切换到background时，触发一次上报。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

内存优化

内存优化模块会在App使用内存过高（超过1GB）时，采集当前状态下的所有内存节点和引用关系，生成内存快照文件并上传。对应的，在平台上可以看到内存过高时App的内存分配情况、通过现场信息排查内存泄漏或者大内存分配等问题。开启内存优化功能需要引入子库MemoryGraph。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
添加以下代码，调用OOMTrigger函数触发内存泄漏。

#import <mach/mach.h>
    //设置的内存采集启动阈值，当App内存超过此值时将启动内存优化模块，采集App内存状态
    static float dangerousMemoryThreshold = 1024.0;
            
    //计算App当前的内存占用，当内存占用超过内存采集启动阈值时，返回true，否则返回false
    bool overMemoryThreshold(void)
    {
        kern_return_t kr;
                
        task_vm_info_data_t task_vm;
        mach_msg_type_number_t task_vm_count = TASK_VM_INFO_COUNT;
        kr = task_info(mach_task_self(), TASK_VM_INFO, (task_info_t) &task_vm, &task_vm_count);
                   
        if (kr == KERN_SUCCESS) {
            printf("Current App Memory is :%f\n\n", task_vm.phys_footprint / (1024.0 * 1024.0));
            if (task_vm.phys_footprint / (1024.0 * 1024.0) > dangerousMemoryThreshold) {
                return true;
            } else {
                return false;
            }
        }
            
        return false;
    }
            
    //触发内存泄漏，当App当前内存占用小于内存采集启动阈值时，会不断触发内存泄漏
    - (void)OOMTrigger{
        dispatch_async(dispatch_get_global_queue(0, 0), ^{
            while (1) {
                if (!overMemoryThreshold()) {
                    CGSize size = CGSizeMake(1024 * 8, 1024 * 8 * 9.0f/16.0);
                    const size_t bitsPerComponent = 8;
                    const size_t bytesPerRow = size.width * 4;
                    CGContextRef ctx = CGBitmapContextCreate(calloc(sizeof(unsigned char), bytesPerRow * size.height), size.width, size.height, bitsPerComponent, bytesPerRow, CGColorSpaceCreateDeviceRGB(), kCGImageAlphaPremultipliedLast);
                    CGContextSetRGBFillColor(ctx, 1.0, 1.0, 1.0, 1.0);
                    CGContextFillRect(ctx, CGRectMake(0, 0, size.width, size.height));
                    sleep(1);
                } else {
                    break;
                }
            }
        });
    }

上报策略

App内存状态采集后，会在下一次App启动时进行上报。
上报内存文件前，会先向Server请求是否允许上传。如果Server不允许上传，则会在下一次App启动时重新请求。未通过请求的内存文件会缓存在App的沙盒中，当Server允许上传时一起上传。更多信息，请参见如何判断Server是否允许上传内存文件？。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

网络分析

网络分析模块需要引入子库Network。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
您可以发送一些网络请求触发SDK网络数据记录。

上报策略

网络分析日志记录后不会立即上报，在以下时间会自动上报：

• App启动15s之后，触发一次上报。
• 每经过60s，触发一次上报。
• 当App状态切换到background时，触发一次上报。

如果您不想或者只想监控某些URL的网络请求，可以在网络请求配置中进行配置。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

日志回捞

日志回捞模块需要引入子库APMLog。通过使用SDK提供的接口进行打点，可以记录一些App运行期间产生的日志。此模块是一种基于mmap的高效率的日志打点框架，日志压缩率高达25倍，结合云控可以实现线上用户日志的实时定向回捞，帮助您高效精准的定位和解决问题。
日志不会全部上报，获取这些日志的方式如下：

• 崩溃发生后，自动上报崩溃发生前一段时间产生的日志。
  上报的日志在崩溃详情页的自定义日志里查看。
• 下发云控命令，获取指定设备或用户、指定时间内产生的日志。更多信息请参见回捞。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
对于C/C++、Objective-C和Swift，APMPlus提供了三类日志打点的接口，每一类有四个接口：Debug、Info、Warn、Error，代表日志严重程度的四个等级，可以在平台查看日志时进行筛选。

//无论使用哪类接口，首先都需要先调用如下接口开启Alog功能
//注意：仅在App启动时调用一次即可
#import "RangersAPM+ALog.h"

[RangersAPM setALogEnabled];  //启用Alog
[RangersAPM enableConsoleLog];  //同时在控制台输出日志

//Objective-C 可以使用如下接口进行日志打点
#import "RangersAPM+ALog.h"

//第一个参数标识当前日志的业务、场景等信息；
//第二个参数为日志具体信息，可以使用format类型，如果使用format，需要继续传入对应的参数
 RANGERSAPM_ALOG_DEBUG(@"Business", @"version : %@", [self version]);  //Debug类日志
 RANGERSAPM_ALOG_INFO(@"Business", @"version : %@", [self version]);   // Info类日志
 RANGERSAPM_ALOG_WARN(@"Business", @"version : %@", [self version]);   //Warn类日志
 RANGERSAPM_ALOG_ERROR(@"Business", @"version : %@", [self version]);   //Error类日志
  
//C/C++ 可以使用如下接口进行日志打点
#import "RangersAPM_ALog.h"
 
//第一个参数标识当前日志的业务、场景等信息；
//第二个参数为日志具体信息，可以使用format类型，如果使用format，需要继续传入对应的参数
 RANGERSAPM_ALOG_DEBUG_C("Business", "version : %s", version());
 RANGERSAPM_ALOG_INFO_C("Business", "version : %s", version());
 RANGERSAPM_ALOG_WARN_C("Business", "version : %s", version());
 RANGERSAPM_ALOG_ERROR_C("Business", "version : %s", version());
 
//Swift 可以使用如下接口进行日志打点
#import "RangersAPM+ALog.h"

//第一个参数为日志具体信息
//tag 标识当前日志的业务、场景等信息；
//fileName 为当前所在文件名，可以参考示例传入 #file
//funcName 为当前所在方法名，可以参考示例传入 #function
//line 为当前所在文件的行号，可以参考示例传入 #line
RangersAPM.debugALog("alogtest", tag: "Business", fileName: #file, funcName: #function, line: #line)
RangersAPM.infoALog("alogtest", tag: "Business", fileName: #file, funcName: #function, line: #line)
RangersAPM.warnALog("alogtest", tag: "Business", fileName: #file, funcName: #function, line: #line)
RangersAPM.errorALog("alogtest", tag: "Business", fileName: #file, funcName: #function, line: #line)

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

CPU监控

CPU监控模块包含两个子模块：CPU指标和CPU异常。

• CPU指标模块：需要引入Monitors子库。
  监控App运行过程中的CPU使用情况，同时SDK版本需要高于2.7.3。
• CPU异常模块：需要引入子库CPUException。
  监控App运行过程中CPU使用率过高的场景，并记录当时的调用堆栈。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
CPU指标会在App运行时自动上报。以下示例代码模拟CPU使用率过高场景，触发CPU异常的上报。

for (int i = 0; i < 10; i++) {
        NSString *queueName = [NSString stringWithFormat:@"com.apmplus.testcpu%d",i];
        dispatch_queue_t queue = dispatch_queue_create([queueName UTF8String], DISPATCH_QUEUE_SERIAL);
                dispatch_async(queue, ^{
                        int count = 0;
                        while (1) {
                                count++;
                        }
                });
}

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

MetricKit

MetricKit模块会监控MetricKit.framework生成的系统日志，并上报给平台。如需接入，请引入MetricKit子库，同时APMPlus SDK版本需要高于2.12.1。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
系统会每天生成一份MetricKit日志，提供给业务方。如果想测试是否接入成功，请在真机调试状态下，执行如下操作：

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

Disk

Disk模块会监控沙盒的使用情况。同时，将生成指标和异常信息上报给平台。如需接入，请引入Disk子库，同时APMPlus SDK版本需要高于3.0.0。

测试用例

测试用例是通过在项目中添加样例代码并在合适的时机触发，来验证SDK能否捕获对应事件的日志。您可以参见各模块给出的样例代码和说明，或者参见Demo工程。
为了防止检索沙盒文件，影响用户体验。磁盘监控启动时，Disk模块会在程序后台检索沙盒文件并上报。

日志说明

完成开启Debug日志后，根据输出日志验证模块是否接入成功。

自定义回捞

自定义回捞可以按照配置拉取沙盒或内存中指定的信息到APMPlus平台，进行问题排查或数据分析。如需接入，请引入CloudCommand子库，同时APMPlus SDK版本需要高于3.5.3。

测试用例

1. 创建响应回捞命令的类。

   #import <Foundation/Foundation.h>
   #import "RangersAPM+CloudCommand.h"
   
   NS_ASSUME_NONNULL_BEGIN
   // 继承自自定义回捞基类
   @interface APMPlusCustomCloudHandler : RangersAPMCustomCommandBase
   @end
   NS_ASSUME_NONNULL_END
   

   #import "APMPlusCustomCloudHandler.h"
   
   @implementation APMPlusCustomCloudHandler
   // 响应回捞参数中的 command 值
   + (NSString *)cloudCommandIdentifier {
       return @"pull_file";
   }
   /// 创建用于执行指令的实例变量
   + (instancetype)createInstance {
       static APMPlusCustomCloudHandler *handler = nil;
       static dispatch_once_t onceToken;
       dispatch_once(&onceToken, ^{
           handler = [[APMPlusCustomCloudHandler alloc] init];
       });
       return handler;
   }
   
   /// 执行自定义命令
   - (void)executeCustomCommandWithParams:(NSDictionary *)params completion:(RangersAPMCustomCommandCompletion)completion {
       
       RangersAPMCustomCommandResult *result = [[RangersAPMCustomCommandResult alloc] init];
       // 待上报的字典信息
       result.specificParams = @{@"aKey": @"aValue", @"bKey": @"bValue"};
       // 待上报文件的二进制信息
       ...
       result.data = [NSData dataWithContentsOfFile:toBeUplodFilePath];
       // 待上报文件的名称
       result.fileName = @"custom_file_name";
       if (completion) {
           completion(result);
       }
   }
   /// 上传结果到服务器成功
   - (void)uploadCustomCommandResultSucceededWithParams:(NSDictionary *)params {
       NSLog(@"------ %s", __func__);
   }
   /// 上传结果到服务器失败
   - (void)uploadCustomCommandResultFailedWithParams:(NSDictionary *)params error:(NSError *)error {
       NSLog(@"------ %s", __func__);
   }
   @end
   

2. 注册响应回捞命令的类。
   在RangersAPM启动后，调用如下代码，注入自定义回捞响应类。

   // 注册自定义回捞类
   [RangersAPM addCustomCommandHandlerCls:[APMPlusCustomCloudHandler class]];
   

3. 新建自定义回捞任务。详情请参见新建日志回捞任务。
   在回捞参数中，添加以下内容。

   {
       "business_Akey":"business_Avalue",
       "business_Bkey":"business_Bvalue",
       "command":"pull_file"
   }
   

   • command：在iOS工程中，会通过该字段的值将命令分发给不同的handler来执行。
   • 其他字段请按照业务需求，请自行配置。

日志说明