文档中心

应用性能监控全链路版

SDK 接入

接入说明

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

使用限制

PC 端 SDK 目前仅限中国大陆应用使用。

获取SDK

步骤一：下载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
Windows (MSVC)		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 框架开发的应用皆属于此类。Parfait 提供了 C++ Public API，用户需要通过桥接的方式接入 Parfait 的能力。即：

APP JS/C#/GO/... -> C Wrapper -> Parfait C++ API

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

下载安装CMake。CMake下载官网

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

parfait_c_wrapper.zip

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

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

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

说明

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

App同时链接wrapper库和Parfait SDK。

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

注意

如果需要新增功能或者可更改的参数，直接修改parfait_wrapper.h和parfait_wrapper.cpp，再执行一次编译命令。

如果仅需要升级SDK版本，不需要更改接口，可以将SDK二进制直接替换为最新版本，不需要重新编译，Parfait SDK ABI兼容。

接入SDK

步骤一：链接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共用同一套头文件，添加头文件依赖。

步骤四：初始化SDK

操作步骤

打开调试日志。

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

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

创建并初始化Wrapper。

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

// 创建parfait wrapper
ParfaitWrapperBase* CreateParfaitWrapper();

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

设置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？。

设置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信息，用于崩溃列表页面的过滤，初始化后可更改。	-

示例代码

接入能力

步骤一：统计进程状态（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();

步骤三：接入其他功能

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

功能	接入文档
基础数据统计
PV/UV统计	请参考上文的“统计进程状态”
埋点
自定义事件/自定义日志	自定义事件/自定义日志
ALog日志	ALog日志
异常监控
崩溃监控	崩溃监控
性能监控
CPU/Memory监控	性能监控
归因功能
自定义文件上传	辅助文件上传
云控回捞	ALog日志 - 步骤二：上报日志 - 回捞命令上报
平台基础功能帮助文档
符号表上传	符号表管理

步骤四：多进程接入

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

子进程像主进程一样接入Parfait SDK。

主进程再初始化一个用于代表子进程的wrapper。主进程和子进程通过IPC通信，传递数据。主进程往wrapper里面写数据。

更多复杂情况，可以在控制台发起工单。

退出SDK

调用此接口后，所有Parfait实例都会销毁。调用后默认中断所有上传任务。

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

注意

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

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

最近更新时间：2026.02.10 19:56:16

这个页面对您有帮助吗？

有用

无用