应用接入iOS SDK--应用性能监控全链路版-火山引擎

文档中心

立即注册

导航

应用接入iOS SDK

最近更新时间：2024.11.14 14:28:12首次发布时间：2021.06.15 18:04:44

应用性能监控全链路版的iOS SDK基本为无侵入式，App接入SDK后可以进行崩溃分析、错误分析、卡顿分析等各种监控指标的分析，帮助优化和定位问题。本文介绍产品形态为App的详细的接入步骤。

注意事项

iOS SDK有中国大陆（不包括港澳台地区）和海外两个版本，功能相同上报地址不同。
- 中国发布的应用：使用CN子库，上报到中国大陆服务器。
- 海外发布的应用：使用Global子库且SDK版本大于等于5.1.0，上报到马来西亚柔佛服务器。
  注意
  柔佛是开白地域，如需查看该地域接入的应用和功能页面，请提交工单。
调用SDK初始化接口不会采集用户信息，调用SDK启动接口会开始采集用户信息，请确保采集用户信息之前已经获得用户授权。详情请参见SDK隐私政策。

Demo说明

APMPlus_iOS

Demo已经接入了SDK的所有能力。
您可以通过Demo制造一些崩溃和性能数据。
可以修改Demo中的AppID和AppToken，把性能数据上报到控制台以查看。

Demo中提供了各功能模块的子库，子库和模块的对应关系如下表所示：

子库	说明	对应平台模块	开始支持版本
Crash	崩溃监控：捕获CPP Exception、Mach Exception、NSException Exception 和 Signal Exception	崩溃分析	0.0.5
WatchDog	卡死监控：监控主线程长时间卡住被系统 watchdog给强杀的情况	崩溃分析	0.0.5
OOM	Out of memory监控	崩溃分析内存优化-OOM趋势	0.0.5
LAG	卡顿监控：监控主线程短时间内无法响应的情况	卡顿分析	0.0.5
UserException	自定义错误，需要业务方手动打点	错误分析-自定义错误	0.0.5
Monitors	启动分析：流畅性：	用户体验-启动分析用户体验-页面体验内存优化-OOM趋势-扩展指标	0.0.7
UITrackers	页面分析：	用户体验-页面体验-页面响应	0.0.7
Hybrid	WKWebView H5 页面监控	页面监控	0.0.8
MemoryGraph	内存分析，获取某一时刻APP的内存状态	内存优化	0.0.8
Network	网络分析：网络错误，Http、DNS分析	网络分析错误分析-网络错误	1.0.0
NetworkPro	网络分析：网络错误，Http、DNS分析	网络分析错误分析-网络错误	2.5.2
EventMonitor	事件分析，记录自定义事件，需要手动埋点	事件分析	2.0.0
SessionTracker	PV/UV统计，接入后会自动上报数据	各模块异常率、异常用户比例等	2.3.0
APMLog	APM日志库，可以手动打点记录APP运行日志	日志回捞崩溃分析-崩溃详情-自定义日志	2.4.0
CrashProtector	崩溃防护	异常防护-崩溃防护	2.5.2
CPUException	CPU异常监控	CPU监控-CPU异常	2.7.3
MetricKit	MetricKit 的稳定性	MetricKit-稳定性	2.12.1
MetricKit	MetricKit 的性能	MetricKit-性能	3.5.3
Disk	磁盘监控	磁盘监控	3.0.0
GWPASan	GWPASan	崩溃分析	3.1.0
Coredump	Coredump	崩溃分析	3.2.0
BootingProtect	连续崩溃保护	-	2.10.0
BootingProtectLite	连续崩溃保护Lite版（不依赖OOM）	-	2.10.0
Zombie	线上Zombie分析	崩溃分析	2.8.0（不支持白名单） 2.10.0（支持白名单）
CloudCommand	回捞功能	单点追查-回捞	3.5.3
HybridPro	新版 WKWebView H5 页面监控	新H5监控	3.10.0

步骤一：获取SDK包

在Podfile中，添加如下示例代码，获取SDK包。

platform :ios, '10.0'
source 'https://github.com/volcengine/volcengine-specs.git'

pod 'RangersAPM', '5.1.3', :subspecs => [
    'Crash',
    'WatchDog',
    'OOM',
    'LAG',
    'UserException',
    'Monitors',
    'UITrackers',
    'HybridPro',
    'MemoryGraph',
    'NetworkPro',
    'EventMonitor',
    'SessionTracker',
    'APMLog',
    'CrashProtector',
    'CPUException',
    'MetricKit',
    'Disk',
    'GWPASan',
    'Coredump',
    'CloudCommand',
    'CN'      # 与 Global 必须二选其一
    'Global'  # 与 CN 必须二选其一
]

说明

添加上述代码会引入SDK的所有功能，如果不想引入全部功能，请按需引入子库，具体请参见Demo说明。
APMPlus从3.10.0版本起支持苹果在WWDC 23要求的Privacy manifest功能。
CN 与 Global 用来指明数据上报的域名。
- CN：上报到国内服务器
- Global：上报到国外服务器

执行以下命令，安装SDK。
```
pod install
```

步骤二：初始化SDK

说明

初始化SDK阶段，不获取用户个人信息。
建议在AppDelegate.m的application didFinishLaunchingWithOptions:方法中，或者在用户同意隐私政策之后的合适时机，进行初始化SDK的操作。

添加以下示例代码，初始化SDK。

#import <RangersAPM.h>

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

    RangersAPMConfig *apmConfig = [RangersAPMConfig configWithAppID:@"{{app_id}}" appToken:@"{{app_token}}"];
    apmConfig.channel = @"App Store";
    /**
     首次启动由于没有获取到配置，无法确定需要开启哪些功能模块。可以配置此属性，来决定首次启动默认需要开启的功能模块，仅对首次启动生效，一旦拉取到配置，下次启动就会先读取本地缓存的配置来决定。
1. 建议默认开启崩溃分析（RangersAPMCrashMonitorSwitch）、启动分析（RangersAPMLaunchMonitorSwitch）、网络分析（RangersAPMNetworkMonitorSwitch），避免一些和首次启动强相关的数据丢失.
2. 配置默认开启模块后，新设备首次启动会默认打开这些模块，可能会出现平台上关闭了这些模块，但是依然有数据上报的情况，可能会给您的事件量造成意外的消耗；请根据您的应用情况灵活配置。
3. 配置多个模块可以参考这种写法：RangersAPMCrashMonitorSwitch | RangersAPMNetworkMonitorSwitch | RangersAPMLaunchMonitorSwitch
     */
    apmConfig.defaultMonitors = RangersAPMCrashMonitorSwitch;

    return YES;
}

说明

{{app_id}}和{{app_token}}须替换为您创建的应用对应的AppID和AppToken，具体请参见如何查询AppID和AppToken？。

步骤三：启动SDK并开启数据采集

注意

建议启动代码调用时机尽量靠前，否则可能出现启动阶段（启动SDK代码调用之前）发生的崩溃无法捕获，或者启动分析数据产生误差。
建议在AppDelegate.m的application didFinishLaunchingWithOptions:方法中，或者在用户同意隐私政策之后的合适时机，完成启动SDK的操作。

添加以下示例代码，启动SDK并开启数据采集。

#import <RangersAPM.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 使用初始化阶段获取的config启动SDK
    [RangersAPM startWithConfig:apmConfig];
    [RangersAPM setUserID:@"xxxx"];
    [RangersAPM setDeviceID:@"xxxx"]; 
    
    return YES;
}

说明

如果需要使用自定义deviceID，需修改apmConfig的相关参数，具体请参见获取设备数与用户数。

步骤四：上传符号表

符号表可以解析崩溃堆栈的内容，将日志里的堆栈信息由原始堆栈转化成经过符号化之后的解析堆栈。符号表支持手动上传和自动上传两种方式。

手动上传

验证符号表满足以下格式。
把符号表压缩为zip文件。
Mac中zip需要执行以下命令，去除默认生成的DS_Store__MACOSX文件。
```
zip -r test.app.dSYM.zip test.app.dSYM -x "*.DS_Store" -x "__MACOSX"
```
说明
将test.app.dSYM.zip和test.app.dSYM替换为您的符号表名称。
上传符号表。
- 在符号表管理页面上传符号表。详情请参见iOS符号表管理。
- 使用curl命令上传。
```
curl UploadDsymDomain/apmplus_api/eue/guest/app/mapping/upload -F "file=@dSYMZipName" -F "type=Dwarf" -F "os=iOS" -F "aid=APMPlusID" -F "app-token=APMPlusToken" -F "script-version=2.0" -H "Content-Type: multipart/form-data" -w %{http_code}
```
  注意
  - 将命令参数值用 ' " ' 包起来，否则参数中的空格可能导致命令解析错误。
  - 将命令中的UploadDsymDomain替换为您想上报的域名。
    - 国内域名：https://console.volcengine.com。接入 CN subspec 时，请使用这个域名。
    - 国外域名：https://open.apmplus.ap-southeast-1.volces.com。接入 Global subspec 时，请使用这个域名。
  - 将命令中的dSYMZipName替换为您的符号表文件路径，APMPlusID替换为您的AppID，APMPlusToken替换为您的AppToken。
  执行完成后，返回如下即说明上传成功。

自动上传

通过在Xcode中对应Target下，配置Build Phases，添加Run Script，可以实现APP打包时自动上传符号表。

说明

默认Debug模式和模拟器编译不会上传符号表。如果需要在这两种情况下上传符号表，请参见手动上传。

选择Build Settings > Debug Infomation Format下，检查工程配置是生成符号表。
选择Build Phases > New Run Script Phase，添加Run Script。
将添加的Run Script置于最后，防止脚本执行时符号表还没有生成。
在脚本中添加以下命令，在Debug模式和模拟器编译时不会上传符号表。
```
/bin/sh ${PODS_ROOT}/RangersAPM/RangersAPM/Core/APMPlus_DSYMUploader_v2.sh "APMPlusID" "APMPlusToken" "UploadDsymDomain"
```
说明
- APMPlusID和APMPlusToken须替换为您创建的应用对应的AppID和AppToken，具体请参见如何查询AppID和AppToken？。
- 将命令中的UploadDsymDomain替换为您想上报的域名。
  - 国内域名：https://console.volcengine.com。接入 CN subspec 时，请使用这个域名。
  - 国外域名：https://open.apmplus.ap-southeast-1.volces.com。接入 Global subspec 时，请使用这个域名。
- 接入的SDK版本需要大于等于5.1.0。若接入早期版本的SDK，请使用步骤5 的方案。
（可选）修改脚本内容。
如果您接入的SDK为较低版本且不想升级为更高版本，或者需要Debug模式和模拟器编译才能自动上传符号表，请执行以下操作：
1. 下载脚本文件。
  APMPlus_DSYMUploader_v2.sh
  未知大小
2. 将下载的脚本文件内容复制到Run Script中。
3. 修改APMPlus_APP_ID和APMPlus_APP_Token为您的AppID和AppToken。修改APMPlus_UPLOAD_DOMAIN为您想要上报的域名。
  说明
  - 国内域名：https://console.volcengine.com。接入 CN subspec 时，请使用这个域名。
  - 国外域名：https://open.apmplus.ap-southeast-1.volces.com。接入 Global subspec 时，请使用这个域名。
```
#!/bin/sh
################################################################################
# 自定义配置
###############################################################################
# Debug模式编译是否上传，1＝上传 0＝不上传，默认不上传
UPLOAD_DEBUG_SYMBOLS=0

# 模拟器编译是否上传，1＝上传，0＝不上传，默认不上传
UPLOAD_SIMULATOR_SYMBOLS=0

# APMPlusID：应用在APMPlus平台的ID
APMPlus_APP_ID="XXX"

# APMPlusToken: 应用在APMPlus平台的Token
APMPlus_APP_Token="XXX"

# APMPlusUploadDomain：应用上报的域名，请在 [平台 - 应用接入iOS SDK](https://www.volcengine.com/docs/6431/68850#%E6%AD%A5%E9%AA%A4%E5%9B%9B%EF%BC%9A%E4%B8%8A%E4%BC%A0%E7%AC%A6%E5%8F%B7%E8%A1%A8) 查询映射表。
APMPlus_UPLOAD_DOMAIN="XXX"
```
4. 根据需要，修改脚本中的UPLOAD_DEBUG_SYMBOLS和UPLOAD_SIMULATOR_SYMBOLS字段。
  参数
  说明
  UPLOAD_DEBUG_SYMBOLS
  Debug模式编译是否上传。
  1：上传
  0（默认）：不上传
  UPLOAD_SIMULATOR_SYMBOLS
  模拟器编译是否上传。
  1：上传
  0（默认）：不上传

应用性能监控全链路版