Parfait SDK是APMPlus PC监控平台的官方SDK，提供跨平台C++ API，是动态库，可监控应用线上稳定性问题。

步骤一：下载SDK

• 支持平台：Windows(32/64）、macOS(x86_64/arm64)

  说明

  • 所有的业务都能接入MT，MD只有VS2019的业务方能接入。
  • MD支持监控更多的崩溃类型，如果可以建议优先选择接入MD。
• 支持功能：PV/UV统计、埋点、Alog日志、Crash监控、自定义文件上报
• 产物形式：mac为Framework动态库，Windows为/MT和 /MD(VS2019)动态库

平台	架构	产物
Windows (MSVC)	MT： x86 x64	parfait-win_1.4.3.1.zip 未知大小
	MD (VS2019) ： x86 x64 说明 所有的业务都能接入MT，MD只有>=VS2019的业务方可接入。 MD抓的崩溃类型更多，如果能接入就优先选择接入MD。	parfait-win_1.4.3.1.zip 未知大小
macOS (Clang)	x86_64 arm64 fat binray(x86_64+arm64)	parfait-mac_1.4.3.1.zip 未知大小

步骤二：Non-Native App适配接入

Native App指的是使用C/C++开发的应用，Native App可跳过此步骤，直接开始接入SDK。
Non-Native App指的是使用非C/C++语言开发的应用，使用Electron、Flutter框架开发的应用皆属于此类。Parfait提供了C++ Public API，用户需要通过桥接的方式接入Parfait的能力。即：

为了更好支持用户接入SDK，Parfait提供了C Wrapper Demo，封装了主要功能，如初始化、崩溃监控、自定义事件、自定义日志、Alog日志和自定义文件上传功能，供业务接入参考。但因为用户诉求不尽相同，后续需要业务自行维护Wrapper。以下是如何编译Wrapper的步骤：

1. 下载安装CMake。CMake下载官网

2. 下载并解压parfait_c_wrapper.zip。parfait_wrapper.cpp中封装了对Parfait C++ API的调用。
   

   

   parfait_c_wrapper.zip

   未知大小

   

3. 阅读下文的接入SDK和接入能力，按需要修改parfait_wrapper.cpp代码，并确保暴露了C API到parfait_wrapper.h中。

4. 执行以下命令，编译wrapper库。

   cd parfait_c_wrapper
   cmake -B"./output" && cmake --build "./output" --config Release
   

   说明

   mac产物为output目录下的libparfait_wrapper.dylib，win产物为output/Release目录下的parfait_wrapper.dll。

5. App同时链接wrapper库和Parfait SDK。

6. App通过调用wrapper库封装的C API去接入Parfait SDK的能力。

   注意

   • 如果需要新增功能或者可更改的参数，直接修改parfait_wrapper.h和parfait_wrapper.cpp，再执行一次编译命令。
   • 如果仅需要升级SDK版本，不需要更改接口，可以将SDK二进制直接替换为最新版本，不需要重新编译，Parfait SDK ABI兼容。

步骤一：链接SDK

Native app链接parfait sdk即可。Non-Native app需要同时链接parfait_wrapper sdk和parfait sdk。
Windows下建议sdk存放在和app的同级目录中，以免app找不到对应sdk。

步骤二：获取AppID和Token

查询Apmplus平台的AppID和Token，初始化SDK时会用到，见如何查询AppID和AppToken？

步骤三：引入头文件

Windows和Mac共用同一套头文件，添加头文件依赖。

// Windows直接引入头文件
#include "header/ParfaitConstants.h"
#include "header/ParfaitEnvBase.h"
#include "header/ParfaitInstance.h"
#include "header/ParfaitRecorderBase.h"
#include "header/ParfaitWrapperBase.h"
#include "header/ParfaitLogRecorderBase.h"

// mac以framework形式引入
#include <Parfait/ParfaitConstants.h>
#include <Parfait/ParfaitEnvBase.h>
#include <Parfait/ParfaitInstance.h>
#include <Parfait/ParfaitRecorderBase.h>
#include <Parfait/ParfaitLogRecorderBase.h>
#include <Parfait/ParfaitWrapperBase.h>

步骤四：初始化SDK

操作步骤

1. 打开调试日志。
   接入初期可以先打开调试模式，Parfait debug log会输出在控制台。上线后请务必关闭调试模式。

   /**
    * （可选）是否输出parfait内部的debug log，未设置默认为不输出
    * @param  is_debug true输出，false不输出
    */
   static void ParfaitGlobalEnvBuilderBase::SetIsDebug(bool is_debug);
   

2. 创建并初始化Wrapper。
   Wrapper代表一个Parfait实例，初始化之后才能接入功能。一般情况下，持有一个单例wrapper指针即可。

   // 创建parfait wrapper
   ParfaitWrapperBase* CreateParfaitWrapper();
   
   示例代码：
   static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
   

3. 设置Wrapper所需Global Env。
   创建Global Env builder，填写参数；初始化Global Env；销毁Global Env builder。
   单进程内同aid下的所有wrapper共享Global Env中的参数。

   // 创建全局环境变量builder
   ParfaitGlobalEnvBuilderBase* CreateParfaitGlobalEnvBuilder(int64_t aid);
   
   // 基于全局环境变量builder初始化全局环境变量
   void ParfaitWrapperBase::InitGlobalEnv(ParfaitGlobalEnvBuilderBase &global_env_builder);
   
   // 销毁全局环境变量builder
   void DestroyParfaitGlobalEnvBuilder(ParfaitGlobalEnvBuilderBase* &builder);
   

   Global Env参数说明：

   参数	是否必填	含义	默认值
   RootPathName	必填	绝对路径。自定义日志、自定义事件、alog数据存储的根目录。UTF8编码。	-
   Did	必填	设备ID。	-
   Uid	必填	用户ID。	-
   Host	必填	Host域名。	https://apmplus.volces.com
   AppToken	必填	APMPlus平台项目详情中显示的Token。1.4.3.0版本后支持。 未设置，数据不会上传。设置错误，上报返回401。	-
   AppVersion	必填	App版本号。	-
   AppMiniorVersion	选填	App小版本号。	-
   Channel	必填	应用渠道。	-
   BuildID	选填	编译ID。	-
   SessionID	选填	Session ID。	-
   ReportInterval	选填	单位ms，自定义日志、自定义事件、性能监控、网络监控的循环上报间隔时间，不得低于10s。	60s
   InterruptUploadIfExit	选填	SDK destroy时是否中断自定义事件、日志、性能数据、网络监控数据上传。默认中断，如果为'false'，SDK将会把当前正在上传的任务执行完后再退出。	true
   UploadCrashImmediately	选填	发生崩溃后是否立即上传崩溃。默认立即上传，如果设置为禁止立即上传后，应用重启后再上传。	true
   UseMainProcessParamAsChildProcessExceptionUploadParam	选填	允许已接入崩溃监控，但未初始化Parfait SDK的子进程使用主进程的参数上报崩溃。一旦子进程初始化Parfait SDK，将会使用他们自己的参数。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。	子进程使用自己的参数上报报告
   IrreplaceableExceptionMonitor	选填	调用后，崩溃监控不可被其他模块的崩溃监控顶替。默认可被顶替。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。1.4.2.0及之后的版本支持此参数。	崩溃监控可被顶替
   IgnoreExceptionInChildProcess	选填	调用后，子进程崩溃不生成崩溃报告。默认生成崩溃报告。此接口仅在mac平台上生效，必须在主进程初始化崩溃监控前设置。子进程调用此API无效。1.4.2.0及之后版本支持此参数。	mac子进程生成崩溃报告
   AllowExceptionMonitorToBeReplaced	废弃	1.4.2.0及之后的版本废弃此参数。	-

   注意

   如果不注入Host和AppToken信息，SDK不能正常初始化，数据无法上报。AppToken信息，详情请参见如何查询AppID和AppToken？。

4. 设置Wrapper所需Instance Env。
   创建Instance Env builder，填写参数；初始化Instance Env；销毁Instance Env builder。
   Instance Env是每个Wrapper独有的参数。

   // 创建实例环境变量builder
   ParfaitEnvBuilderBase* CreateParfaitEnvBuilder(int64_t aid, const char* instance_name);
   
   // 基于builder初始化实例环境变量
   void ParfaitWrapperBase::InitInstanceEnv(parfait::ParfaitEnvBuilder &env_builder)
   
   // 销毁实例环境变量builder
   void DestroyParfaitEnvBuilder(ParfaitEnvBuilderBase* &builder);
   

   Instance Env说明：

   参数	是否必填	含义	默认值
   Pid	必填	进程ID。	-
   ProcessName	必填	进程名，支持中文，用于平台各类数据筛选（“进程类型”）。	-
   RecordContext	选填	自定义日志、自定义事件的Context信息，用于单点展示以及事件过滤，初始化后不可更改。	-
   CrashContext	选填	崩溃的Context信息，用于崩溃列表页面的过滤，初始化后可更改。	-

示例代码

#define AID 4444
#define ROOT_PATH_NAME "C:\\Users\\Admin\\Documents\\"

static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
//static parfait::ParfaitWrapperBase* parfait_wrapper_ptr2 = nullptr;

void InitParfaitGlobalEnv() {
    // 创建全局环境变量builder
    auto global_env_builder = parfait::CreateParfaitGlobalEnvBuilder(AID);
    // 设置全局环境参数值
    global_env_builder 
        ->SetRootPathName(ROOT_PATH_NAME) // UTF8编码
        .SetHost("https://apmplus.volces.com") 
        .SetAppToken("488e*********f55b") // 请查看平台项目信息获取
        .SetDid("12345") 
        .SetUid("1234")
        .SetAppVersion("1.0.0") 
        .SetChannel("app_store");
    // 初始化全局环境变量
    parfait_wrapper_ptr->InitGlobalEnv(*global_env_builder);
    // 参数已注入，销毁全局环境变量
    parfait::DestroyParfaitGlobalEnvBuilder(global_env_builder); 
}
void InitParfaitInstanceEnv(parfait::ParfaitWrapperBase* wrapper, const char* instance_name) {
    // 创建实例环境变量builder
    auto instance_env_builder = CreateParfaitEnvBuilder(AID, instance_name);
    // 设置实例环境参数值
    instance_env_builder->SetProcessName("main") //进程名，平台上可用“进程类型”筛选数据
                .SetPid(std::to_string(getpid()).c_str()); // 必填
                //.AddRecordContext("record_key", "record_value")//可选，注入额外信息
                //.AddCrashContext("crash_key", "crash_value");//可选，注入额外信息
    // 初始化实例环境变量
    wrapper->InitInstanceEnv(*instance_env_builder);
    // 参数已注入，销毁实例环境变量
    parfait::DestroyParfaitEnvBuilder(instance_env_builder); 
}

void InitParfait() {
    // 输出parfait调试日志，默认不开启, 线上不要开启！
    parfait::ParfaitGlobalEnvBuilderBase::SetIsDebug(true);
    parfait_wrapper_ptr = parfait::CreateParfaitWrapper();
    InitParfaitGlobalEnv();
    InitParfaitInstanceEnv(parfait_wrapper_ptr, "instance1");
    //InitParfaitInstanceEnv(parfait_wrapper_ptr2, "instance1");
}

步骤一：统计进程状态（PV/UV统计）

• 功能介绍
  对应APMPlus上的PV/UV统计大盘展示，同时用于计算崩溃的影响用户率、影响用户数。注意，PV指的是Process View，进程的启动次数；UV指的是Unique Vistor，访问用户数。
• 使用场景
  初始化Parfait后，即可进行PV和UV的统计与上报。

  #include "ParfaitWrapperBase.h"
  namespace parfait {
  /**
   * 启动pv/uv数据上报，用于统计pv/uv以及崩溃影响用户数，初始化完成后立即上报数据
   */
  void ParfaitWrapperBase::LaunchReport();
  }
  
  示例代码：
  parfait_wrapper_ptr->LaunchReport();
  

步骤二：启动间隔上报

• 功能介绍
  调用后Parfait会依据全局环境变量的report_interval值开始间隔循环上报自定义日志/自定义事件/网络监控/性能监控数据。

  注意

  • 本接口仅需要在初始化后调用一次。之后除非退出SDK，不然间隔上报不会停止。
  • 如使用了性能监控功能，或写入了大量的自定义日志/自定义事件，那一定要调用这个接口，防止数据堆积在本地。

  #include "ParfaitWrapperBase.h"
  
  namespace parfait {
  /**
   * @brief Triggers periodical upload. Data are custom events & custom logs & performance
   * data. This can't be disabled once it has been enabled.
   */
  void ParfaitWrapperBase::Upload();
  }
  示例代码：
  parfait_wrapper_ptr->Upload();
  

步骤三：接入其他功能

您可以根据业务需求，按照以下操作接入使用这些功能。

步骤四：多进程接入

绝大部分情况下，一个wrapper以满足单进程所有需求。如多进程需要接入，可选择任选一个方案：

• 子进程像主进程一样接入Parfait SDK。
• 主进程再初始化一个用于代表子进程的wrapper。主进程和子进程通过IPC通信，传递数据。主进程往wrapper里面写数据。
• 更多复杂情况，可以在控制台发起工单。

调用此接口后，所有Parfait实例都会销毁。调用后默认中断所有上传任务。
如果需要停止Parfait所有功能并回收内存，可以直接调用：

#include "ParfaitInstance.h"

namespace parfait {
/**
 * @brief Destroy all Parfait instances. Be careful to use it.
 * @param wrapper Parfait wrapper.
 */
void DestroyParfaitWrapper(ParfaitWrapperBase*& wrapper);
}

示例代码：
parfait_wrapper_ptr->DestroyParfaitWrapper(parfait_wrapper_ptr);