接入说明

更新时间：2023.05.16 16:32:32

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

Native App接入

步骤一：下载SDK

平台	架构	产物
Windows	MT : x86 x64	parfait-win_1.4.1.1.zip 未知大小
MD (VS2019) : x86 x64	parfait-win_1.4.1.1.zip 未知大小
macOS	x86_64 arm64 fat binray(x86_64+arm64)	parfait-mac_1.4.1.0.zip 未知大小

平台

架构

产物

Windows

MT :

parfait-win_1.4.1.1.zip

未知大小

MD (VS2019) :

parfait-win_1.4.1.1.zip

未知大小

macOS

x86_64
arm64
fat binray(x86_64+arm64)

parfait-mac_1.4.1.0.zip

未知大小

SDK说明：

支持平台：Windows(32/64）、macOS(x86_64/arm64)
支持功能：PV/UV统计、埋点、Alog日志、Crash监控、自定义文件上报
产物形式：mac为Framework动态库，Windows为/MT 和 /MD(VS2019)动态库

步骤二：初始化SDK

操作步骤

添加头文件依赖。

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

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

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

创建并初始化Wrapper。
Wrapper代表一个parfait实例，初始化之后，即可调用其他方法。一般一个业务持有一个wrapper指针。简单情况下，wrapper指针作为单例使用即可。
```
// 创建parfait wrapper
ParfaitWrapperBase* CreateParfaitWrapper();

示例代码：
static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
```

设置全局参数。
单进程内同一aid下的所有实例共享此全局环境变量中的参数。

// 创建全局环境变量builder
ParfaitGlobalEnvBuilderBase* CreateParfaitGlobalEnvBuilder(int64_t aid);

// 基于全局环境变量builder初始化全局环境变量
void ParfaitWrapperBase::InitGlobalEnv(ParfaitGlobalEnvBuilderBase &global_env_builder);

// 销毁全局环境变量builder
void DestroyParfaitGlobalEnvBuilder(ParfaitGlobalEnvBuilderBase* &builder);

全局环境参数说明：

参数	是否必填	含义	默认值
RootPathName	必填	绝对路径，自定义日志/自定义事件/alog数据存储的根目录。	-
Did	必填	设备ID	-
Uid	必填	用户ID	-
Host	必填	host域名，以https://开头，请联系商务咨询。	-
AppVersion	必填	App版本号	-
AppMiniorVersion	选填	App小版本号	-
Channel	必填	应用渠道	-
BuildID	选填	编译编号	-
SessionID	选填	Session ID	-
ReportInterval	选填	ms，自定义日志/自定义事件/性能监控/网络监控的循环上报间隔时间，不得低于10s。	60s
InterruptUploadIfExit	选填	SDK destroy时是否中断自定义事件/日志/性能数据/网络监控数据上传，默认中断，如果为'false'，SDK将会把当前正在上传的任务执行完后再退出。	true
UploadCrashImmediately	选填	发生崩溃后是否立即上传崩溃，默认立即上传，如设置为禁止立即上传后，应用重启后再上传。	true
UseMainProcessParamAsChildProcessExceptionUploadParam	选填	允许已接入崩溃监控，但未初始化Parfait SDK的子进程使用主进程的参数上报崩溃。一旦子进程初始化Parfait SDK，将会使用他们自己的参数。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。	false
AllowExceptionMonitorToBeReplaced	选填	允许parfait崩溃监控被其他三方库替换。默认不可被替换。	false

注意

如果不注入Host信息，SDK不能正常初始化，数据无法上报。Host域名请联系商务咨询。

创建实例环境变量。

实例可以理解为同一app下的不同业务线，他们的aid一样，数据报到同一个项目中，但是代码无法共享，所以用instance_name作区分，每个业务线使用自己的实例环境变量。
Parfait支持多进程多实例，每个进程的实例需要特殊设置单独的参数。

// 创建实例环境变量builder
ParfaitEnvBuilderBase* CreateParfaitEnvBuilder(int64_t aid, const char* instance_name);

// 基于builder初始化实例环境变量
void ParfaitWrapperBase::InitInstanceEnv(parfait::ParfaitEnvBuilder &env_builder)

// 销毁实例环境变量builder
void DestroyParfaitEnvBuilder(ParfaitEnvBuilderBase* &builder);

实例环境参数说明：

参数	是否必填	含义	默认值
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)
        .SetHost("https://xxxx.xxxx.xxx") // 联系商务获取 
        .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");
}

Non-Native App接入

由于PC技术栈繁杂，为了更好的支持Electron、Flutter等业务接入Parfait SDK，Parfait提供了C Wrapper Demo，封装了主要功能，如初始化、崩溃监控、自定义事件、自定义日志、Alog日志和自定义文件上传功能，供业务接入参考。后续更新需要业务自行维护。

下载安装CMake。
下载Wrapper包parfait_c_wrapper.zip。
parfait_c_wrapper.zip
未知大小
执行以下命令，解压后编译wrapper库。
cd parfait_c_wrapper
cmake -B"./output" && cmake --build "./output" --config Release
说明
mac产物为output目录下的libparfait_wrapper.dylib，win产物为output/Release目录下的parfait_wrapper.dll。
同时链接wrapper库和Parfait SDK，通过wrapper库封装的C API去调用Parfait SDK接口。
注意
- 如果需要新增功能或者可更改的参数，直接修改parfait_wrapper.h和parfait_wrapper.cpp，再执行一次编译命令。
- 如果仅需要升级SDK版本，不需要更改接口，可以将SDK二进制直接替换为最新版本，不需要重新编译，Parfait SDK ABI兼容。

验证功能

PV/UV统计

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

/**
 * 启动pv/uv数据上报，用于统计pv/uv以及崩溃影响用户数，初始化完成后立即上报数据
 */
void ParfaitWrapperBase::LaunchReport();

// 调用例子：
// 1. sdk初始化完毕，得到本实例的wrapper
parfait_wrapper_ptr->LaunchReport();

启动间隔循环上传（可选）

功能介绍
调用后Parfait会依据全局环境变量的Report Interval值开始间隔循环上报自定义日志/自定义事件/网络监控/性能监控数据。
使用场景
如果有使用网络监控/性能监控这两个功能，或者写入了大量的自定义日志/自定义事件数据，那么业务方一定要调用这个接口，防止数据堆积在本地。
注意事项
Parfait采用单进程单实例上报模式，因此只需要上报进程的上报实例调用一次即可，初始化完成后即可调用。此间隔循环上报除非Parfait退出，不然不会停止。

void ParfaitWrapperBase::Upload();
示例代码：
parfait_wrapper_ptr->Upload();

内存回收

调用此接口后，所有parfait实例都会销毁。

警告

不建议SDK接入方调用该函数，因为同一进程内的其他业务也可能接入Parfait。

如果需要停止Parfait所有功能并回收内存，可以直接调用：

void DestroyParfaitWrapper(ParfaitWrapperBase* &wrapper);

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

注意

此操作可能会发生短暂阻塞，因为回收操作涉及到多线程任务执行等待的操作。假设回收时Parfait里面还有任务在异步执行，delete操作会等待所有异步任务执行完才会回收完所有的内存。

多进程支持

绝大部分情况下，一个parfait wrapper就能搞定所有的需求（一个global env和一个instance env）。下面方案任选一个：

其他进程也接入parfait，和主进程一样的初始化。
主进程再初始化一个wrapper，用于代表子进程。主进程和子进程通过IPC通信，传递数据。
更多复杂情况，可以发起Oncall咨询。

Native App接入

步骤一：下载SDK

步骤二：初始化SDK

Non-Native App接入

验证功能

PV/UV统计

启动间隔循环上传（可选）

内存回收

多进程支持

应用性能监控全链路版

接入说明

Native App接入 #

步骤一：下载SDK #

步骤二：初始化SDK #

操作步骤

示例代码

Non-Native App接入 #

验证功能 #

PV/UV统计 #

启动间隔循环上传（可选） #

内存回收 #

多进程支持 #

Native App接入

步骤一：下载SDK

步骤二：初始化SDK

Non-Native App接入

验证功能

PV/UV统计

启动间隔循环上传（可选）

内存回收

多进程支持