You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
合作与生态
支持与服务
开发者
了解我们
导航

接入说明

更新时间: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
未知大小

SDK说明:

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

步骤二:初始化SDK

操作步骤

  1. 添加头文件依赖。

    // 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>
  2. 开启调试。
    接入初期可以先打开调试模式,Parfait debug log会输出在控制台。上线后请务必关闭调试模式。

    /**
     * (可选)是否输出parfait内部的debug log,未设置默认为不输出
     * @param  is_debug true输出,false不输出
     */
    static void ParfaitGlobalEnvBuilderBase::SetIsDebug(bool is_debug);
  3. 创建并初始化Wrapper。
    Wrapper代表一个parfait实例,初始化之后,即可调用其他方法。一般一个业务持有一个wrapper指针。简单情况下,wrapper指针作为单例使用即可。

    // 创建parfait wrapper
    ParfaitWrapperBase* CreateParfaitWrapper();
    
    示例代码:
    static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
  4. 设置全局参数。
    单进程内同一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域名请联系商务咨询。

  5. 创建实例环境变量。

    • 实例可以理解为同一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日志和自定义文件上传功能,供业务接入参考。后续更新需要业务自行维护。

  1. 下载安装CMake。

  2. 下载Wrapper包parfait_c_wrapper.zip

    parfait_c_wrapper.zip
    未知大小

  3. 执行以下命令,解压后编译wrapper库。
    cd parfait_c_wrapper
    cmake -B"./output" && cmake --build "./output" --config Release

    说明

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

  4. 同时链接wrapper库和Parfait SDK,通过wrapper库封装的C API去调用Parfait SDK接口。

    注意

    • 如果需要新增功能或者可更改的参数,直接修改parfait_wrapper.hparfait_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咨询。