文档中心

崩溃监控

最近更新时间：2023.11.21 14:13:33

首次发布时间：2022.06.20 11:34:32

Parfait内部集成了Google Crashpad作为PC跨平台的crash收集工具，并基于crashpad，拓展开发了windows veh、post handler等等功能。

注意事项

SDK最好不要接，宿主接即可。
初始化Parfait SDK。持有初始化成功的parfait_wrapper_ptr指针。
提供一个有权限操作的路径，用于存储崩溃报告。

完整流程

初始化SDK，在全局变量中设置崩溃监控启动参数。
调用InitCrashServer/InitCrashServerOnWin，确保返回值为true。
发生crash后，crash文件存储路径下会生成.dmp结尾的文件。
- mac/linux：在dump_dir(业务方传入)/pending文件夹下
- windows：在dump_dir(业务方传入)/reports文件夹下
发生crash后，应用退出，crash报告直接上传到APMPlus平台。
两三分钟后，可以在APMPlus PC平台的Crash列表查看该crash。
如果没有上传相关符号表，堆栈表示为unknown。在符号表 - 仅缺失 - 上传页面上传相关符号表，再单击详情页的重新解析，crash堆栈解析成功。

步骤一：设置参数

初始化SDK时，可以设置GlobalEnv的参数，修改崩溃监控的默认行为。

参数	是否必填	含义	默认值
UseMainProcessParamAsChildProcessExceptionUploadParam	选填	允许已接入崩溃监控，但未初始化Parfait SDK的子进程使用主进程的参数上报崩溃。一旦子进程初始化Parfait SDK，将会使用他们自己的参数。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。	子进程使用自己的参数上报报告
IrreplaceableExceptionMonitor	选填	调用后，崩溃监控不可被其他模块的崩溃监控顶替，默认可被顶替。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。1.4.2.0~版本开始支持。	崩溃监控可被顶替
IgnoreExceptionInChildProcess	选填	调用后，子进程崩溃不生成崩溃报告。默认生成崩溃报告。此接口仅在mac平台上生效，必须在主进程初始化崩溃监控前设置。子进程调用此API无效。1.4.2.0~版本开始支持。	mac子进程生成崩溃报告

步骤二：初始化

macOS

Windows

主进程

调用InitCrashServer方法初始化主进程的崩溃监控，dump_dir为存放崩溃报告的绝对路径，同步返回Crashpad初始化结果。

/**
 * 仅Mac/Linux可用
 * 初始化Crashpad，并为调用进程注册Crash监听
 * 调用进程的子进程会自动注册Crash监听，不需要调用InitCrashClient方法
 * @param  dump_dir crash文件存储路径，绝对路径，最后以‘/’结尾
 * @return  Crashpad是否初始化成功
 */
 bool ParfaitWrapperBase::InitCrashServer(const char* dump_dir);
 
/**
 * 仅Mac/Linux可用
 * 在parfait初始化前初始化Crashpad，参数和上面一致
 * 初始化parfait后仍需要调用上述的InitCrashServer，才能上传Crash文件
 * ⚠️应用生命周期内，Crashpad只会初始化一次，参数以第一次初始化为准
 */
 static bool ParfaitWrapperBase::InitCrashServerEarly(const char* dump_dir); 

示例代码： 二选一即可
//场景1(推荐): 主进程在初始化parfait sdk后注册崩溃监控
bool init_res = parfait_wrapper_ptr->InitCrashServer("your_absolute_path/");//传入绝对路径

//场景2: 适用于特殊场景，主进程需要在初始化parfait sdk之前就注册崩溃监控
bool init_res = parfait::ParfaitWrapperBase::InitCrashServerEarly("your_absolute_path/");
parfait sdk 初始化代码
//仅提醒parfait上传Crash文件，dmp_path务必保持和InitCrashServerEarly保持一致
parfait_wrapper_ptr->InitCrashServer("your_absolute_path/");

子进程

同一进程组：主进程初始化崩溃监控后，该进程的所有子进程会自动注册崩溃监控，不需要再进行别的操作。请注意主进程必须在拉起子进程前初始化崩溃监控！
不同进程组：需要主动为子进程重新注册崩溃监控，流程和主进程一样。

沙盒应用

沙盒应用需要额外操作。

选定一个identifier。例如，macdemo。
- 格式为xxxx。
- 中间可用.作分隔，如xxx.xxxx。
- 只能是字母组合。
- identifier不要太长。
主应用配置entitlements。
- 新增两个用于支持bootstrap服务的key。
  - com.apple.security.temporary-exception.mach-lookup.global-name
  - com.apple.security.temporary-exception.mach-register.global-name
- 类型是String， Value是com.bytedance.parfait.child_port_handshake.$identifier。
  
  这里key的Value都是com.bytedance.parfait.child_port_handshake.macdemo。
给parfait_crash_handler二进制签名。
AppStore要求应用内所有的macho文件都必须开启沙箱才能过审，所以您需要为parfait_crash_handler二进制签名。parfait_crash_handler二进制位于Parfait.framework/Versions/A/Resources目录下。
执行以下命令，为parfait_crash_handler开启sandbox，并继承主应用的权限。
```
codesign --force --sign "$YOUR_INDENTITY" --entitlements "$PATH/parfait_crash_handler.entitlements" "$PATH/parfait_crash_handler"
```
parfait_crash_handler.entitlements.zip
1.03KB

验证parfait_crash_handler签名是否成功。

codesign -dvvv --entitlements :- $PATH/parfait_crash_handler

修改代码。
在初始化崩溃监控之前，调用SetCrashServerIdentifierOnMac注入identifier信息。

#define CRASH_FILE_DIR "crash_databse"

std::string homeDir = getenv("HOME");
homeDir.append(CRASH_FILE_DIR);
parfait::ParfaitWrapperBase::SetCrashServerIdentifierOnMac("macdemo");
bool res = parfait_wrapper_ptr->InitCrashServer(homeDir.c_str());
if (res)
    printf("Init Crashpad success");
else
    printf("Init Crashpad failed");

验证是否调用成功。
- InitCrashServer API 返回true或者打开parfait debug log，控制台会输出Crashpad init success!。
- 非调试模式下，发生崩溃后崩溃会立即上报到APMPlus平台。
提审时说明原因。
因为使用了Temporary Exception Entitlements，提审时需要说明使用原因。此权限是为了注册崩溃监控，崩溃监控用于收集程序运行情况。

主进程

将parfait_crash_handler.exe存放至项目空间下（parfait_crash_handler.exe在产物包中）。
首先需要实现CrashServerInitCallback回调方法。callback会返回初始化结果和子进程注册崩溃监控所需的值。
在主进程的主线程调用InitCrashServerOnWin初始化Crash模块，为主进程注册崩溃监控。Windows下默认异步初始化，1.1.3版本后支持同步初始化。

/**
 * 仅Windows可用
 * ⚠️注意：必须在主进程的主线程中调用！！
 * 异步初始化Crashpad，并为调用进程注册Crash监听
 * @param  handler_path crashpad_handler.exe的绝对路径，最后以crashpad_handler.exe结尾
 * @param  dump_dir crash文件存储路径，绝对路径，最后以‘\’结尾
 * @param  callback 返回异步初始化Crashpad的结果和其他进程调用InitCrashClientOnWin注册崩溃监听需要的ipc_pipe
 */
void ParfaitWrapperBase::InitCrashServerOnWin(const char* handler_path, const char* dump_dir, CrashServerInitCallback callback);

/**
 * 仅Windows可用
 * 在parfait初始化前初始化Crashpad，并为调用进程注册Crash监听
 * ⚠️注意：必须在主进程的主线程中调用！！Crashpad只会初始化一次，参数以第一次初始化为准!!
 * ⚠️注意：初始化parfait后仍需要调用上述的InitCrashServerOnWin，才能上传Crash文件
 * @param  handler_path crashpad_handler.exe的路径，最后以crashpad_handler.exe结尾
 * @param  dump_dir crash文件存储路径，最后以‘\’结尾
 * @param  async_start 异步初始化, true的话callback返回异步初始化结果，本方法返回false，false该方法同步返回crashpad初始化结果，
 * @param  callback 返回异步初始化Crashpad结果和其他进程调用InitCrashClientOnWin注册崩溃监听需要的ipc_pipe
 */
static bool ParfaitWrapperBase::InitCrashServerOnWinEarly(const char* handler_path, const char* dump_dir, bool async_start, CrashServerInitCallback callback); 

示例代码： 二选一即可
//场景1(推荐): 主进程可以在初始化parfait sdk后异步注册崩溃监控
parfait sdk 初始化代码
parfait_wrapper_ptr->InitCrashServerOnWin("xxxxxxx\crashpad_handler.exe", "xxxxX\crashData\", &getCrashpadInitRes);

//场景2: 适用于特殊场景，主进程需要在初始化parfait sdk之前就同步注册崩溃监控
bool init_res = parfait::ParfaitWrapperBase::InitCrashServerOnWinEarly("xxxxxxx\parfait_crash_handler.exe", "xxxxx\crashData\", false, &getCrashpadInitRes);
parfait sdk 初始化代码
//仅提醒parfait上传Crash文件，dmp_path务必保持和InitCrashServerEarly保持一致
parfait_wrapper_ptr->InitCrashServerOnWin("xxxxxxx\crashpad_handler.exe", "xxxxX\crashData\", nullptr);

子线程

拿到回调后返回的ipc_pipe值后，可为其他进程注册崩溃监控。下面是在其他进程中的示例代码：

/**
 * 仅Windows可用
 * 为当前进程注册Crash监听
 * @param  ipc_pipe InitCrashServerOnWin的callback获得的ipc_pipe值
 * @return  当前进程是否成功注册崩溃监听
 */
bool ParfaitWrapperBase::InitCrashClientOnWin(const char* ipc_pipe);
/**
 * 仅Windows可用
 * 在parfait初始化前为当前进程注册Crash监听，参数和上面一致
 * ⚠️调用本方法后不需要再调用上面的InitCrashClientOnWin方法
 */
static bool ParfaitWrapperBase::InitCrashClientOnWinEarly(const char* ipc_pipe); 
示例代码： 二选一即可
//e.g. 二选一即可
//场景1(推荐): 子进程只需要注册崩溃监听
bool res = parfait::ParfaitWrapperBase::InitCrashClientOnWinEarly(ipc_pipe);

//场景2: 子进程还需要使用parfait其他功能
parfait sdk 初始化代码
bool res = parfait_wrapper_ptr->InitCrashClientOnWin(ipc_pipe);

（可选）特定异常捕获

原生Crashpad只能捕获走UEF的异常，无法捕获只走VEH->SEH的异常，如堆破坏。为捕获这些异常，parfait Crashpad注册了VEH，并默认捕获堆破坏异常。
VEH捕获异常后会生成dmp文件并继续将异常抛出。如果业务方需要捕获特定类型的异常，可以查阅winnt.h中异常类型错误码添加VEH目标异常类型。

注意

VEH捕获异常生成dmp后，UEF不会再次生成dump文件。崩溃监控初始化前后调用都可以。
请不要随意调用此接口，会造成非预期行为，请咨询后再调用。

/**
 * 仅Windows可用
 * Crashpad VEH默认捕获Heap Corruption类型异常，业务方可自定义设置其他需要捕获的异常类型
 * VEH捕获异常后会生成dmp文件，并将异常抛出
 * @param  exception_type_code 异常的错误码，可在winnt.h中查询, e.g.STATUS_ACCESS_VIOLATION/0xC0000005L
 */
static void ParfaitWrapperBase::AddVehTargetExceptionType(const unsigned long exception_type_code);

示例代码：
parfait::ParfaitWrapperBase::AddVehTargetExceptionType(0xC0000005L);

步骤三：上报Crash

parfait会在崩溃后立即上传报告，如上报失败，报告会留到下次启动再传。业务无需关心上报时机。

步骤四：消费Crash

Crash查询

崩溃上传后，您可以在APMPlus PC平台的崩溃趋势页面，查看已上报的崩溃。

符号表上传

请参见崩溃趋势的符号表部分上传符号表。
崩溃报告中只会记录堆栈地址，想要看到堆栈符号，需要上传符号表。
APMPlus PC会收集Windows和Mac的系统符号表，业务仅需要上传业务符号表。
APMPlus通过模块名（exe/dll/dylib/so等文件的名字）+ uuid（每次编译唯一）匹配符号表。如果崩溃详情页没有符号信息，代表没有上传模块对应的符号表。

（可选）步骤五：接入其他功能

崩溃附加Filter Context

上下文信息用于筛选Crash信息。筛选条件为键值对。

初始化SDK时，实例环境变量可调用ParfaitEnvBuilderBase::AddCrashContext新增CrashContext信息。如果用该实例初始化Parfait Crashpad，Crashpad会带上该实例的CrashContext信息。
初始化SDK后，可调用ParfaitWrapperBase::AddCrashContext新增或修改当前实例CrashContext信息。
不同的parfait实例，可以拥有不同的CrashContext信息。如果需要更新Parfait Crashpad中的Crash Context信息，还需要调用RefreshCrashContextInCrashServer方法。

/**
 * 添加崩溃的Context信息，用于单点展示以及崩溃列表页面的过滤
 * @param  key 键
 * @param  value 值
 */
ParfaitEnvBuilderBase& ParfaitEnvBuilderBase::AddCrashContext(const char* key, const char* value);
/**
 * 三端可用，更新当前实例的CrashContext，用于单点展示以及崩溃列表页面的过滤，上传崩溃文件/抓获崩溃时附带上传
 * 如使用了parfait的崩溃监听服务，需要再调用RefreshCrashContextInCrashServer方法更新CrashServer中的CrashContext
 * @param  key key值，不可为空
 * @param  value value值，不可为空
 */
 void ParfaitWrapperBase::AddCrashContext(const char* nonullable_key, const char* nonullable_value);
/**
 * 三端可用，更新Crashpad的CrashContext为当前实例的CrashContext
 */
 void ParfaitWrapperBase::RefreshCrashContextInCrashServer();

崩溃附加场景信息

添加场景信息后，您可筛选目标场景下的Crash。

struct ParfaitWrapperBase::CrashAnnotation {
    const char* scene = nullptr; // 当前场景
};
   
/**
 * 三端可用，崩溃后parfait crashpad会自动带上crash annotation字段信息，所有进程共享字段，可随时调用
 * e.g. 应用刚启动，设置scene为launch
 */
static void ParfaitWrapperBase::SetCrashAnnotation(const CrashAnnotation* annotation);

崩溃后回调

注意

暂时只有windows系统支持崩溃后回调。
1.3.0.0及之后的SDK版本支持崩溃后回调。
崩溃后回调请谨慎操作，如果有不当操作可能会导致二次崩溃。

崩溃后，业务希望在客户端做一些操作，可以调用此方法。crashpad上报完crash后，会在崩溃进程调用传入的nonnullable_crash_callback方法。

/**
 * @brief Type of crash callback func ptr.
 */
typedef void (*CrashCallback)();


/**
 * @brief Only avaliable on Windows temporarily.
 * Sets the Crash Callback object in current process. This callback will be called after crash. Be careful to use
 * since some operations would result in second crash.
 *
 * @param nonnullable_crash_callback callback
 */
static void ParfaitWrapperBase::SetCrashCallback(const CrashCallback nonnullable_crash_callback);

崩溃后拉起业务UI处理进程

注意

暂时只有windows系统支持崩溃后拉起业务UI处理进程。

在崩溃后，业务希望有更多的业务交互，可以调用此方法。parfait支持功能有：

(Required) 新起一个业务自定义进程。
(Optional) 拷贝当前崩溃dmp文件到业务指定目录下，同时该文件路径作为参数传递给自定义进程。

(Optional) Parfait是否需要依据自定义进程返回结果来决定崩溃的后续处理（上传/不上传直接删除），同时可以指定Parfait的最长等待时间。自定义进程的返回结果必须是以下三种：

/**
 * @brief List of legal authorization value returned by crash post handler.
 */
enum CrashPostHandlerResult {
  // Unknown. The dmp file will be deleted.
  Crash_Post_Handler_Result_Unknown     = 0,  
  // Allows to upload dmp file.
  Crash_Post_Handler_Result_Upload_Dump = 1,  
  // Doesn't allow to upload dmp file. The dmp file will be deleted.
  Crash_Post_Handler_Result_Delete_Dump = 2, 
}

struct CrashPostHandlerData {
  const unsigned int struct_size = sizeof(CrashPostHandlerData);
  // 必填，业务自定义处理进程地址，崩溃后会自动拉起
  const char* process_path = nullptr;  
  // 选填，拷贝dmp的目的目录，parfait会自动copy dmp到此目录下，并传递dump_path参数给自定义处理进程
  const char* dump_copy_dir = nullptr; 
  // 选填，如果为‘true’，parfait会等待自定义处理进程返回授权结果再来处理当前崩溃，等待最长时间为wait_result_timeout_s，超时后直接删除。可返回结果看CrashPostHandlerResult详情。默认'false'直接上传。
  bool wait_result_for_dump_handle = false;
  // 选填，如果wait_result_for_dump_handle为true，parfait等待的最长时间
  unsigned long wait_result_timeout_s = 120;
} 

/** 在崩溃监听进程内设置业务自定义处理进程，崩溃后parfait会帮忙拉起相应进程，并传入dmp地址（如有）
 * ⚠️注意：暂时只支持windows
 * @param  data 业务自定义处理进程相关信息
 * @return  是否成功设置
 */
 static bool ParfaitWrapperBase::SetCrashPostHandlerInCrashServer(const CrashPostHandlerData* data);

注意事项

完整流程

步骤一：设置参数

步骤二：初始化

步骤三：上报Crash

步骤四：消费Crash

Crash查询

符号表上传

（可选）步骤五：接入其他功能

崩溃附加Filter Context

崩溃附加场景信息

崩溃后回调

崩溃后拉起业务UI处理进程

应用性能监控全链路版

崩溃监控

注意事项

完整流程

步骤一：设置参数

步骤二：初始化

主进程

子进程

沙盒应用

步骤三：上报Crash

步骤四：消费Crash

Crash查询

符号表上传

（可选）步骤五：接入其他功能

崩溃附加Filter Context

崩溃附加场景信息

崩溃后回调

崩溃后拉起业务UI处理进程