腾讯云可观测平台 API 说明

本文详细介绍终端性能监控 Pro SDK 的各功能接口，帮助您更加灵活、深度的使用 SDK。
回调接口
设置 Crash 处理回调
终端性能监控 Pro 处理 Crash 异常时可以回调业务，业务可以在回调中加入自定义的逻辑，或提供额外信息跟随异常一起上报。
public interface CrashHandleListener {
﻿
    /**
     * Crash处理回调时，此接口返回的数据以附件的形式上报，附件名userExtraByteData
     * @param isNativeCrashed 是否Native异常
     * @param crashType 异常的类型
     * @param crashStack 异常堆栈
     * @param nativeSiCode native异常时的SI_CODE，非Native异常此数据无效
     * @param crashTime native异常的发生时间
     * @return 上报的附件字节流
     */
    byte[] getCrashExtraData(boolean isNativeCrashed, String crashType, String crashAddress,
            String crashStack, int nativeSiCode, long crashTime);
﻿
    /**
     * Crash处理回调时，此接口返回的数据在附件extraMessage.txt中展示
     * @param isNativeCrashed 是否Native异常
     * @param crashType 异常的类型
     * @param crashStack 异常堆栈
     * @param nativeSiCode native异常时的SI_CODE，非Native异常此数据无效
     * @param crashTime native异常的发生时间
     * @return 上报的数据
     */
    String getCrashExtraMessage(boolean isNativeCrashed, String crashType, String crashAddress,
            String crashStack, int nativeSiCode, long crashTime);
﻿
    /**
     * Crash处理回调前，执行此接口
     * @param isNativeCrashed 是否Native异常
     */
    void onCrashHandleStart(boolean isNativeCrashed);
﻿
    /**
     * Crash处理回调后，执行此接口
     * @param isNativeCrashed 是否Native异常
     * @return 返回值没有实际作用，不影响方法正常使用，可忽略
     */
    boolean onCrashHandleEnd(boolean isNativeCrashed);
﻿
    /**
     * Crash处理回调时，执行此接口
     * @param isNativeCrashed 是否NativeCrash
     * @param crashType Crash类型
     * @param crashMsg Crash消息， 例如 “Attempt to invoke virtual method 'int java.lang.String.length()' on a null object reference” （4.4.1.2新增）
     * @param crashAddress Crash地址
     * @param crashStack Crash堆栈
     * @param nativeSiCode native异常时有效，SI_CODE
     * @param crashTime crash时间
     * @param userId crash时用户ID
     * @param deviceId crash时的设备ID
     * @param crashUuid 这条异常的唯一标识
     * @return 返回值没有实际作用，不影响方法正常使用，可忽略
     */
    boolean onCrashSaving(boolean isNativeCrashed, String crashType, String crashMsg, String crashAddress,
        String crashStack, int nativeSiCode, long crashTime, String userId, String deviceId,
        String crashUuid, String processName);
}
在初始化阶段，通过 BuglyBuilder 设置，如下所示：
CrashHandleListener crashHandleListener = xxx;
buglyBuilder.setCrashHandleListener(crashHandleListener);
设置 Crash 上报回调
终端性能监控 Pro 上报 Crash 异常时可以回调业务，业务可以在回调中加入自定义的逻辑。
public interface UploadHandleListener {
﻿
        /**
         * 上报开始时回调
         * int TYPE_JAVA_CRASH = 0;  // Java 崩溃
         * int TYPE_NATIVE_CRASH = 1; // Native崩溃
         * int TYPE_JAVA_CATCHED = 2; // Java错误上报
         * int TYPE_ANR_CRASH = 3; // ANR
         * int TYPE_U3D_CRASH = 4; // U3D错误上报
         * @param requestKey 上报关键字（4.4.3.4版本开始，这个字段表示上报异常个例类型，取值如上）
         */
        public void onUploadStart(int requestKey);
﻿
        /**
         * 上报结束后回调
         * int TYPE_JAVA_CRASH = 0;  // Java 崩溃
         * int TYPE_NATIVE_CRASH = 1; // Native崩溃
         * int TYPE_JAVA_CATCHED = 2; // Java错误上报
         * int TYPE_ANR_CRASH = 3; // ANR
         * int TYPE_U3D_CRASH = 4; // U3D错误上报
         * @param requestKey 上报关键字（4.4.3.4版本开始，这个字段表示上报异常个例类型，取值如上）
         * @param responseKey 回包的关键字
         * @param sended 发送的字节流
         * @param recevied 接受的字节流
         * @param result true则上报成功，否则失败
         * @param exMsg 额外信息
         */
        public void onUploadEnd(int requestKey, int responseKey, long sended, long recevied, boolean result, String exMsg);
} 
在初始化阶段，通过 BuglyBuilder 设置，如下所示：
UploadHandleListener uploadHandleListener = null;
buglyBuilder.setUploadHandleListener(uploadHandleListener);
注意：
UploadHandleListener 的 requestKey 参数，从4.4.3.4版本开始，这个字段用于描述上报个例类型，取值如下：
int TYPE_JAVA_CRASH = 0;  // Java 崩溃
int TYPE_NATIVE_CRASH = 1; // Native 崩溃
int TYPE_JAVA_CATCHED = 2; // Java 错误上报
int TYPE_ANR_CRASH = 3; // ANR
int TYPE_U3D_CRASH = 4; // U3D 错误上报
其他接口
其他接口的调用均需在 SDK 初始化之后，初始化之前调用无效，SDK 提供其他接口功能如下。
更新设备 ID
/**
 * 更新设备id（初始化后）
 * @param context context
 * @param deviceId 设备id
 */
public static void updateUniqueId(Context context, String deviceId);
更新用户 ID
/**
 * 更新用户id（初始化后）
 * @param context context
 * @param userId 用户id
 */
public static void updateUserId(Context context, String userId);
更新设备型号
SDK 默认不获取手机型号，业务可以在合规获取到手机型号后通过该接口更新至终端性能监控 Pro SDK。
/**
 * 更新设备型号（初始化后）
 * @param context context
 * @param model 设备型号
 */
public static void updateDeviceModel(Context context, String model);
更新日志等级
/**
 * 更新日志等级（初始化后）
 * @param logLevel 日志等级，级别可从BuglyLogLevel中获取
 */
public static void updateLogLevel(int logLevel);
上报自定义异常
如业务需要上报除 Java Crash、Native Crash、ANR 之外的错误，如 C#异常等，可以通过自定义异常接口上报至终端性能监控 Pro，上报的数据在 终端性能监控 Pro > 错误 页面展示。
/**
 * 上报自定义异常
 * @param thread 出错线程, 默认当前线程
 * @param category 异常类型 u3d c# : 4 ｜ js : 8 ｜ cocos2d lua : 6
 * @param errorType 错误类型
 * @param errorMsg 错误信息
 * @param stack 出错堆栈
 * @param extraInfo 额外信息
 */
public static void postException(Thread thread, int category, String errorType, String errorMsg,
                                     String stack, Map<String, String> extraInfo);
public static void postException(int category, String errorType, String errorMsg,
                                     String stack, Map<String, String> extraInfo);
上报 Java catch 异常
如业务在 Java 中通过 try catch 方式捕获到异常，希望上报到终端性能监控 Pro，可以使用上报 Java catch 异常接口，上报的数据在 终端性能监控 Pro > 错误 页面展示。
/**
 * 处理catch异常并上报.
 * @param thread 出错线程
 * @param exception 异常
 * @param extraMsg 额外信息
 * @param extraData 额外数据
 * @param enableAllThreadStack 开启全部线程抓栈，默认开启
 * @return 上报结果
 */
public static boolean handleCatchException(Thread thread, Throwable exception, String extraMsg,
                                               byte[] extraData, boolean enableAllThreadStack);
public static boolean handleCatchException(Thread thread, Throwable exception, String extraMsg,
                                               byte[] extraData);                                               
设置个例标签
/**
 * 非线程安全，推荐切到相同线程操作
 * 设置个例标签，来自终端性能监控Pro管理台的标签ID
 * 1. 先在终端性能监控Pro管理台添加标签，得到标签ID；
 * 2. 通过setCaseLabels设置标签ID，需要设置多个时，通过英文竖线分割；
 * 3. 异常个例上报时会同时上报这些标签ID；
 * 示例："123|456|789"
 * SDK版本: 4.3.2.9+
 * @param labels 个例标签
 */
public static void setCaseLabels(String labels);
设置业务下钻
/**
 * 非线程安全，推荐切到相同线程操作
 * 设置「业务下钻」标签，设置多个标签时通过英文的竖线分割
 * 最多只允许设置30个标签，超出时，只取前面30个
 * 每个标签最长不超过1024个字符，超出时会添加失败
 * 示例："test_one|test_two|test_three"
 * SDK版本: 4.4.1+
 * @param labels 业务下钻标签
 */
public static void setTestLabels(String labels);
设置 Java 内存泄漏嫌疑对象（性能监控）
在开启终端性能监控 Pro Java 内存泄漏监控后，可以通过如下接口设置疑似泄漏的对象给 SDK 进行监控，若不设置该接口，SDK 只对 Activity/Fragment 对象的内存泄漏进行监控。
/**
 * 设置Java内存泄漏嫌疑对象
 * @param leakObj 嫌疑对象
 */
public static void startInspectLeakObj(Object leakObj);
测试接口
SDK 提供接口测试崩溃异常，业务在调试时可以使用该接口进行崩溃采集上报的测试。
/**
 * 测试crash
 * @param crashType crash类型，可填入Bugly.JAVA_CRASH、Bugly.NATIVE_CRASH、Bugly.ANR_CRASH
 */
public static void testCrash(@CrashTypeKey int crashType);
业务自定义日志接口
SDK 提供异常时业务自定义日志携带能力，业务可以在崩溃发生前（不含回调）调用以下接口写入自定义日志。
public class BuglyCustomLog {
    public static void v(String tag, String msg) {
        BuglyLog.v(tag, msg);
    }
﻿
    public static void d(String tag, String msg) {
        BuglyLog.d(tag, msg);
    }
﻿
    public static void i(String tag, String msg) {
        BuglyLog.i(tag, msg);
    }
﻿
    public static void w(String tag, String msg) {
        BuglyLog.w(tag, msg);
    }
﻿
    public static void e(String tag, String msg) {
        BuglyLog.e(tag, msg);
    }
﻿
    public static void e(String tag, String msg, Throwable throwable) {
        BuglyLog.e(tag, msg, throwable);
    }
﻿
    /**
     * 设置写入日志的缓存大小，日志将根据设置的缓存大小循环写入
     * @param size 日志缓存大小
     */
    public static void setCache(int size) {
        BuglyLog.setCache(size);
    }
}
在写入自定义日志后，如果进程发生异常，会将自定义日志进行上报展示，展示为附件中的 BuglyLog.zip。
自定义数据
添加/移除自定义数据（Crash 监控）
SDK 支持业务添加自定义数据，可以保存在 Crash 发生时、或发生前的一些自定义环境信息。自定义数据会随异常一起上报，并在异常个例详情界面的自定义字段中展示。自定义数据最多支持50对 key-value。
/**
 * 添加自定义数据
 * @param context context
 * @param key key
 * @param value value
 */
public static void putUserData(Context context, String key, String value);
如需移除自定义数据，可通过如下接口进行移除操作。
/**
 * 移除用户自定义数据.
 * @param key key
 * @return 如果存在，则返回对应key的值
 */
public static String removeUserData(Context context, String key);
设置/更新自定义文件上传路径（Crash 监控）
SDK 支持业务上传自定义大文件，并关联至异常个例。自定义文件的上传采用独立于异常上报的通道，对异常处理流程无干扰，且支持配置多个文件。业务可以在发生异常之前的任意时间段，通过如下接口设置/更新文件路径的数组。进程发生异常重启后，会上报这些自定义文件，在异常个例的附件中，展示为custom_log.zip。
/**
 * 设置或更新自定义文件路径数组
 * @param files 文件路径数组，最多10个文件，且压缩后大小不能超过10MB
 * @return 设置结果
 */
public static boolean setAdditionalAttachmentPaths(String[] files);
重要提醒：
该接口最多设置10个文件路径。
需上传文件压缩后的大小限制为10MB，若超过该大小，则不会被上传。
该接口可被多次调用，更新的文件路径会覆盖之前的值。
自定义文件的上传时机在进程二次启动时，与异常上报间存在一定延迟。
频繁发生崩溃异常会触发文件清理逻辑，可能会导致文件漏传。
可以通过配置设置自定义文件上传的采样率。
进入/退出自定义场景（性能监控）
在性能监控中，业务可以自定义场景，并根据场景来执行特定的监控或回调操作。使用如下接口来进入、退出自定义场景。
/**
 * 进入自定义场景
 * @param sceneName 场景名称
 */
public static void enterScene(String sceneName);
﻿
/**
 * 退出自定义场景
 * @param sceneName 场景名称
 */
public static void exitScene(String sceneName);
注意：
enterScene --- exitScene 期间，各监控能力监控到问题时，上报的场景取[自定义场景]。
exitScene 后，各监控能力监控到问题时，上报的场景取 [simpleName Of lastResumedActivity]。
推荐使用 enterScene/exitScene 成对调用，形如：enterScene(A) -> exitScene(A) -> enterScene(B) -> exitScene(B)。如果没有使用成对调用，如下示例：
enterScene(A) --> 自定义场景为 A
enterScene(B) --> 自定义场景为 B
enterScene(C) --> 自定义场景为 C
exitScene(B) --> 自定义场景为 C
exitScene(C) --> 自定义场景为空
exitScene(A) --> 自定义场景为空
如果 sceneName 为空，直接返回。
添加/移除自定义数据采集器（性能监控）
SDK 性能监控模块的自定义设置方式不同于 Crash 监控模块，性能监控模块的自定义数据支持两类：自定义维度与自定义字段。
自定义维度：指由 SDK 指定了三组 Key（详情请参见 ICustomDataEditor），每组10个。应用可以根据需要，选择合适的 Key 上报数据。在控制管理台，用户可以给这些 Key 设置别名，方便查看和分析。对于自定义维度，服务器存储时是一个字段，一个字段分开存储的。后续可以提供丰富的查询和分析能力。当前支持全局设置，或者数据上报前的回调设置。当前支持通过Bugly.getGlobalCustomDataEditor 获取全局接口，设置自定义维度，也可以通过指标类回调（ICustomDataCollector）或问题类回调（ICustomDataCollectorForIssue），设置或者更新自定义维度。
自定义字段：指 Key 和 Value 都由应用自由设置，SDK 不理解字段的类型，统一作为字符串存储。用户可以在控制管理台，在问题列表和问题详情，通过自定义字段查询包含指定内容的上报。当前只支持通过问题类回调 ICustomDataCollectorForIssue，设置自定义字段。
全局设置
全局设置指应用可以随时调用全局设置接口，设置自定义维度，相同 Key 的数据，重复设置表示更新。性能上报在需要上报时，会获取全局缓存的自定义维度数据。
可以通过如下接口来获取默认的全局自定义维度收集回调，并设置全局自定义维度。
/**
 * 获取全局自定义维度设置接口
 * @return 全局自定义维度设置类
 */
public static ICustomDataEditor getGlobalCustomDataEditor();
﻿
// 设置示例
ICustomDataEditor customDataEditor = Bugly.getGlobalCustomDataEditor();
customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());
回调设置
回调设置指应用设置回调，在监控到相关问题上报前，会回调应用的接口，应用根据具体的问题及场景，分别采集额外的现场信息。回调设置分为，指标类回调以及问题类回调。
// 添加回调，指标类回调和问题类回调需要分别设置。
Bugly.addCustomDataCollector(customDataEditor);
﻿
// 移除回调，指标类回调和问题类回调需要分别移除。
Bugly.removeCustomDataCollector(customDataDditor);
﻿指标类回调
：ICustomDataCollector，如卡顿指标，内存峰值属于指标类回调。会在信息采集，缓存数据前，回调应用是否需要补充额外信息。
/**
 * 设置指标数据回调，对于不同监控项、不同场景可设置多个
 * @param dataCollector 全局自定义数据回调类
 */
public static void addCustomDataCollector(ICustomDataCollector dataCollector);
/**
 * 移除全局自定义数据回调
 * @param dataCollector 全局自定义数据回调类
 */
public static void removeCustomDataCollector(ICustomDataCollector dataCollector);
﻿
// 设置示例
ICustomDataEditor customDataEditor = new ICustomDataCollector() {
    @Override
    public void collectCustomData(String pluginName, String scene, ICustomDataEditor customDataEditor) {
        customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
        customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());
    }
};
﻿
// 设置指标类回调
Bugly.addCustomDataCollector(customDataEditor);
// 移除指标类回调
Bugly.removeCustomDataCollector(customDataDditor);
问题类回调：ICustomDataCollectorForIssue，如卡顿问题监控，Java内存泄露，大图分析属于问题类回调，会在监控到异常问题时，回调用户是否需要补充额外信息。
/**
 * 设置单个指标、问题自定义数据回调，对于不同监控项、不同场景可设置多个
 * @param issueDataCollector 单个指标、问题自定义数据回调类
 */
public static void addCustomDataCollector(ICustomDataCollectorForIssue issueDataCollector);
/**
 * 移除单个指标、问题自定义数据回调
 * @param issueDataCollector 单个指标、问题自定义数据回调类
 */
public static void removeCustomDataCollector(ICustomDataCollectorForIssue issueDataCollector);
﻿
// 设置示例
ICustomDataCollectorForIssue issueDataCollector = new ICustomDataCollectorForIssue() {
    @Override
    public void collectCustomData(String pluginName, String scene, ICustomDataEditorForIssue customDataEditor) {
        // 允许覆盖全局设置的自定义维度
        customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
        customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());
    }
}
// 设置问题类回调
Bugly.addCustomDataCollector(issueDataCollector);
// 移除问题类回调
Bugly.removeCustomDataCollector(issueDataCollector);
动态开关
如业务需在指定场景中，动态开关终端性能监控 Pro Crash 监控项或性能监控项，可以通过如下接口进行动态开关。但需注意，崩溃异常的动态开关非必要不应使用，会导致异常的漏报。
/**
 * crash监控动态开关
 * @param crashType crash类型，可填入Bugly.JAVA_CRASH、Bugly.NATIVE_CRASH、Bugly.ANR_CRASH
 * @param isAble true 打开，false 关闭
 */
public static void setCrashMonitorAble(@CrashTypeKey int crashType, boolean isAble);
﻿
/**
 * 性能监控动态开关(开关一组监控项)
 * @param monitorList 监控项list，可从BuglyMonitorName中获取
 * @param isAble true 打开，false 关闭
 */
public static void setPerformanceMonitorsAble(List<String> monitorList, boolean isAble);
﻿
/**
 * 性能监控动态开关(开关单个监控项)
 * @param monitorName 监控项
 * @param isAble true 打开，false 关闭
 */
public static void setPerformanceMonitorAble(String monitorName, boolean isAble);
﻿
/**
 * 停止所有的性能监控项
 */
public static void abolishPerformanceMonitors();
启动监控
默认情况下，启动监控取首个 Activity 的首帧渲染结束作为启动结束点，应用也可以通过 reportAppFullLaunch 接口自定义启动结束点。除此之外，AppLaunch 还提供添加自定义标签接口，以及自定义打点接口。
AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.reportAppFullLaunch();
自定义标签：为本次启动数据添加自定义标签，方便后续做下钻分析，如下所示：
AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.addTag("show_splash");
自定义打点：即在启动过程中，针对启动流程，监控一些耗时任务。
AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.spanStart("login", null); // 登陆任务开始
....
appLaunch.spanStart("verification_code", "login"); // 验证码任务开始
....
appLaunch.spanEnd("verification_code"); // 验证码结束
....
appLaunch.spanEnd("login"); // 登陆结束
AppLaunch 接口的详细说明：
public interface AppLaunch {
    /**
     * 开始启动监控
     * @param context Context
     */
    void install(Context context);
﻿
    /**
     * 添加自定义标签
     * @param tag 自定义标签
     */
    void addTag(String tag);
﻿
    /**
     * Span开始打点
     * @param spanName 开始打点的span名称
     * @param parentSpanName 当前要打点的span的父span的名称
     */
    void spanStart(String spanName, String parentSpanName);
﻿
    /**
     * Span结束打点
     * @param spanName 结束打点的span名称
     */
    void spanEnd(String spanName);
﻿
    /**
     * 标记启动完成
     */
    void reportAppFullLaunch();
}
﻿
﻿
API 说明

本页目录：

回调接口

设置 Crash 处理回调

设置 Crash 上报回调

其他接口

更新设备 ID

更新用户 ID

更新设备型号

更新日志等级

上报自定义异常

上报 Java catch 异常

设置个例标签

设置业务下钻

设置 Java 内存泄漏嫌疑对象（性能监控）

测试接口

业务自定义日志接口

自定义数据

添加/移除自定义数据（Crash 监控）

设置/更新自定义文件上传路径（Crash 监控）

进入/退出自定义场景（性能监控）

添加/移除自定义数据采集器（性能监控）

全局设置

回调设置

动态开关

启动监控
