You need to enable JavaScript to run this app.
导航

接入说明

最近更新时间2024.03.04 14:21:04

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

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

步骤一:接入SDK

Native App接入

  1. 下载SDK。

    平台

    架构

    产物

    Windows

    MT :

    • x86
    • x64
    parfait-win_1.4.2.2.zip
    未知大小

    MD (VS2019) :

    • x86
    • x64

    说明

    • 所有的业务都能接入MT,MD只有VS2019的业务方能接入。
    • MD抓的崩溃类型更多,如果能接入就优先选择接入MD。
    parfait-win_1.4.2.2.zip
    未知大小

    macOS

    • x86_64
    • arm64
    • fat binray(x86_64+arm64)
    parfait-mac_1.4.2.2.zip
    未知大小

    SDK说明:

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

      说明

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

    1. 链接动态库。

    2. 添加头文件依赖。

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

      /**
       * (可选)是否输出parfait内部的debug log,未设置默认为不输出
       * @param  is_debug true输出,false不输出
       */
      static void ParfaitGlobalEnvBuilderBase::SetIsDebug(bool is_debug);
      
    4. 创建并初始化Wrapper。
      Wrapper代表一个Parfait实例,初始化之后才能接入功能。一般情况下,持有一个单例wrapper指针即可。

      // 创建parfait wrapper
      ParfaitWrapperBase* CreateParfaitWrapper();
      
      示例代码:
      static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
      
    5. 设置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

      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信息,SDK不能正常初始化,数据无法上报。

    6. 设置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") 
              .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();

步骤三:接入其他功能

除了常用的功能外,SDK还支持一些增强功能。您可以根据业务需求,按照以下操作使用这些功能。

步骤四:退出SDK

调用此接口后,所有Parfait实例都会销毁。

警告

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

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

void DestroyParfaitWrapper(ParfaitWrapperBase* &wrapper);

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

注意

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

步骤五:多进程接入

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

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