tencent cloud

Tencent Cloud Observability Platform

API Description

Download
Focus Mode
Font Size
Last updated: 2026-05-25 18:01:55
This article describes the feature APIs of the Terminal Performance Monitoring Pro (RUM Pro) SDK to facilitate flexible and in-depth integration.

Callback APIs

Configuring the Crash Handling Callback

RUM Pro can trigger a callback to your business logic when handling a crash. You can add custom logic in the callback or provide additional information to be reported along with the exception.
public interface CrashHandleListener {

/**
* During the crash handling callback, the data returned by this API is reported as an attachment named userExtraByteData.
* @param isNativeCrashed Indicates whether the crash is a native exception.
* @param crashType Exception type.
* @param crashStack Exception stack.
* @param nativeSiCode SI_CODE for the native exception. This data is invalid for non-native exceptions.
* @param crashTime Time when the native exception occurs.
* @return Byte stream of the reported attachment.
*/
byte[] getCrashExtraData(boolean isNativeCrashed, String crashType, String crashAddress,
String crashStack, int nativeSiCode, long crashTime);

/**
* During the crash handling callback, the data returned by this API is displayed in the attachment extraMessage.txt.
* @param isNativeCrashed Indicates whether the crash is a native exception.
* @param crashType Exception type.
* @param crashStack Exception stack.
* @param nativeSiCode SI_CODE for the native exception. This data is invalid for non-native exceptions.
* @param crashTime Time when the native exception occurs.
* @return Reported data.
*/
String getCrashExtraMessage(boolean isNativeCrashed, String crashType, String crashAddress,
String crashStack, int nativeSiCode, long crashTime);

/**
* This API is executed before the crash handling callback.
* @param isNativeCrashed Indicates whether the crash is a native exception.
*/
void onCrashHandleStart(boolean isNativeCrashed);

/**
* This API is executed after the crash handling callback.
* @param isNativeCrashed Indicates whether the crash is a native exception.
* @return The return value has no practical meaning. It does not affect the normal use of this method and can be ignored.
*/
boolean onCrashHandleEnd(boolean isNativeCrashed);

/**
* This API is executed during the crash handling callback.
* @param isNativeCrashed Indicates whether the crash is a native crash.
* @param crashType Crash type.
* @param crashMsg Crash message. For example, "Attempt to invoke virtual method 'int java.lang.String.length()' on a null object reference" (added in version 4.4.1.2).
* @param crashAddress Crash address.
* @param crashStack Crash stack.
* @param nativeSiCode SI_CODE. This is valid for native exceptions.
* @param crashTime Crash time.
* @param userId User ID at the time of the crash.
* @param deviceId Device ID at the time of the crash.
* @param crashUuid Unique identifier for this exception.
* @return The return value has no practical meaning. It does not affect the normal use of this method and can be ignored.
*/
boolean onCrashSaving(boolean isNativeCrashed, String crashType, String crashMsg, String crashAddress,
String crashStack, int nativeSiCode, long crashTime, String userId, String deviceId,
String crashUuid, String processName);
}
During the initialization phase, configure the callback via BuglyBuilder as shown below:
CrashHandleListener crashHandleListener = xxx;
buglyBuilder.setCrashHandleListener(crashHandleListener);

Configuring the Crash Reporting Callback

RUM Pro can trigger a callback to your business logic when reporting a crash. You can add custom logic in the callback.
public interface UploadHandleListener {

/**
* Callback triggered when the reporting starts.
* int TYPE_JAVA_CRASH = 0; // Java crash.
* int TYPE_NATIVE_CRASH = 1; // Native crash.
* int TYPE_JAVA_CATCHED = 2; // Java error reporting.
* int TYPE_ANR_CRASH = 3; // Application Not Responding (ANR).
* int TYPE_U3D_CRASH = 4; // U3D error reporting.
* @param requestKey Reporting keyword (starting from version 4.4.3.4, this field indicates the type of the reported exception case; valid values are shown above).
*/
public void onUploadStart(int requestKey);

/**
* Callback triggered after the reporting ends.
* int TYPE_JAVA_CRASH = 0; // Java crash.
* int TYPE_NATIVE_CRASH = 1; // Native crash.
* int TYPE_JAVA_CATCHED = 2; // Java error reporting.
* int TYPE_ANR_CRASH = 3; // ANR.
* int TYPE_U3D_CRASH = 4; // U3D error reporting.
* @param requestKey Reporting keyword (starting from version 4.4.3.4, this field indicates the type of the reported exception case; valid values are shown above).
* @param responseKey Keyword of the response packet.
* @param sended Byte stream sent.
* @param recevied Byte stream received.
* @param result True indicates successful reporting. False indicates failure.
* @param exMsg Additional information.
*/
public void onUploadEnd(int requestKey, int responseKey, long sended, long recevied, boolean result, String exMsg);
}
During the initialization phase, configure the callback via BuglyBuilder as shown below:
UploadHandleListener uploadHandleListener = null;
buglyBuilder.setUploadHandleListener(uploadHandleListener);
Note:
Starting from version 4.4.3.4, the requestKey parameter of UploadHandleListener is used to describe the type of the reported exception case. Its valid values are as follows:
int TYPE_JAVA_CRASH = 0; // Java crash
int TYPE_NATIVE_CRASH = 1; // Native crash
int TYPE_JAVA_CATCHED = 2; // Java error reporting
int TYPE_ANR_CRASH = 3; // ANR
int TYPE_U3D_CRASH = 4; // U3D error reporting

Other APIs

You need to call other APIs after SDK initialization. Calls made before the initialization are invalid. The SDK provides the following additional APIs.

Updating the Device ID

/**
* Updates the device ID (after initialization).
* @param context Context.
* @param deviceId Device ID.
*/
public static void updateUniqueId(Context context, String deviceId);

Updating the User ID

/**
* Updates the user ID (after initialization).
* @param context Context.
* @param userId User ID.
*/
public static void updateUserId(Context context, String userId);

Updating the Device Model

The SDK does not collect the phone model by default. You can use this API to update the phone model to the RUM Pro SDK after the model is obtained in a compliant manner.
/**
* Updates the device model (after initialization).
* @param context Context.
* @param model Device model.
*/
public static void updateDeviceModel(Context context, String model);

Updating the Log Level

/**
* Updates the log level (after initialization).
* @param logLevel Log level, which can be obtained from BuglyLogLevel.
*/
public static void updateLogLevel(int logLevel);

Reporting a Custom Exception

If you need to report errors other than Java crashes, native crashes, and ANR, such as C# exceptions, you can use the custom exception API to report them to RUM Pro. The reported data is displayed on the Terminal Performance Monitoring Pro > Error page.
/**
* Reports a custom exception.
* @param thread Thread where the error occurs. The default value is the current thread.
* @param category Exception type. U3D C# : 4 | JavaScript : 8 | Cocos2d Lua : 6.
* @param errorType Error type.
* @param errorMsg Error message.
* @param stack Error stack.
* @param extraInfo Additional information.
*/
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);

Reporting a Caught Java Exception

If you want to report an exception caught in a Java try-catch block to RUM Pro, you can use the caught Java exception reporting API. The reported data is displayed on the Terminal Performance Monitoring Pro > Error page.
/**
* Handles and reports a caught exception.
* @param thread Thread where the error occurs.
* @param exception Exception.
* @param extraMsg Additional information.
* @param extraData Additional data.
* @param enableAllThreadStack Specifies whether to enable stack trace capturing for all threads. This is enabled by default.
* @return Reporting result.
*/
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);

Configuring a Case Tag

/**
* This is not thread-safe. It is recommended to switch to the same thread for this operation.
* Configures case tags using the tag IDs in the RUM Pro console.
* 1. First, add a tag in the RUM Pro console to obtain the tag ID.
* 2. Configure the tag ID using setCaseLabels. To configure multiple tags, separate them with a vertical bar (|).
* 3. These tag IDs are reported along with the exception case.
* Example: "123|456|789".
* SDK version: 4.3.2.9+
* @param labels Case tags.
*/
public static void setCaseLabels(String labels);

Configuring Business Drill-Down

/**
* This is not thread-safe. It is recommended to switch to the same thread for this operation.
* Configures business drill-down tags. To configure multiple tags, separate them with a vertical bar (|).
* A maximum of 30 tags can be configured. If more than 30 tags are specified, only the first 30 tags are used.
* Each tag cannot exceed 1024 characters in length. Tags longer than this limit cannot be added successfully.
* Example: "test_one|test_two|test_three".
* SDK version: 4.4.1+
* @param labels Business drill-down tags.
*/
public static void setTestLabels(String labels);

Configuring a Suspected Object for Java Memory Leaks (Performance Monitoring)

After you enable Java memory leak monitoring in RUM Pro, you can use the following API to configure suspected leak objects for the SDK to monitor. If this API is not configured, the SDK only monitors memory leaks for Activities and Fragments.
/**
* Configures a suspected object for Java memory leaks.
* @param leakObj Suspected object.
*/
public static void startInspectLeakObj(Object leakObj);

Test API

The SDK provides an API to test crashes. During debugging, you can use this API to test crash collection and reporting.
/**
* Crash testing.
* @param crashType Crash type. Valid values: Bugly.JAVA_CRASH, Bugly.NATIVE_CRASH, and Bugly.ANR_CRASH.
*/
public static void testCrash(@CrashTypeKey int crashType);

Custom Log APIs

The SDK provides the capability to attach custom logs in the event of an exception. Before a crash occurs (excluding callbacks), you can call the following APIs to write custom logs.
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);
}

/**
* Configures the log cache size. Logs are written in a loop based on the configured cache size.
* @param size Log cache size.
*/
public static void setCache(int size) {
BuglyLog.setCache(size);
}
}
After custom logs are written, if an exception occurs in the process, the custom logs will be reported and displayed as BuglyLog.zip in the attachment.

Custom Data

Adding and Removing Custom Data (Crash Monitoring)

The SDK allows you to add custom data to save custom environment information at the time of a crash or before it occurs. The custom data is reported along with the exception and displayed in the Custom Field section on the exception case details page. You can add a maximum of 50 key-value pairs as custom data.
/**
* Adds custom data.
* @param context context
* @param key key
* @param value value
*/
public static void putUserData(Context context, String key, String value);
If you need to remove custom data, use the following API.
/**
* Removes custom data.
* @param key key
* @return If the data exists, the value for the key is returned.
*/
public static String removeUserData(Context context, String key);

Configuring and Updating a Custom File Upload Path (Crash Monitoring)

The SDK allows you to upload custom large files and associate them with exception cases. Custom file uploads use a separate channel from exception reporting, ensuring no interference with the exception handling process. Multiple files can be configured. You can configure and update the array of file paths via the following API at any time before an exception occurs. After the process restarts due to an exception, the custom files will be reported and displayed as custom_log.zip in the attachment of the exception case.
/**
* Configures or updates the custom file path array.
* @param files File path array. A maximum of 10 files is allowed. The compressed size cannot exceed 10 MB.
* @return Configuration result.
*/
public static boolean setAdditionalAttachmentPaths(String[] files);
Important:
This API allows a maximum of 10 file paths.
The compressed size limit for the uploaded files is 10 MB. Files exceeding this limit are not uploaded.
This API can be called multiple times, and the updated file paths will overwrite the previous values.
The custom files are uploaded during the second startup of the process, introducing a delay relative to exception reporting.
Frequent crashes may trigger the file cleanup logic, which may lead to missed file uploads.
The sampling rate for custom file uploads can be configured.

Activating and Deactivating a Custom Scenario (Performance Monitoring)

In performance monitoring, you can customize scenarios and execute specific monitoring or callback operations based on these scenarios. You can use the following APIs to activate and deactivate custom scenarios.
/**
* Activates a custom scenario.
* @param sceneName Scenario name.
*/
public static void enterScene(String sceneName);

/**
* Deactivates a custom scenario.
* @param sceneName Scenario name.
*/
public static void exitScene(String sceneName);
Note:
When a scenario is active (between enterScene and exitScene), if an issue is detected, the reporting scenario is the [custom scenario].
After exitScene is called, if an issue is detected, the reporting scenario is [simpleName Of lastResumedActivity].
It is recommended to use enterScene and exitScene in pairs, such as: enterScene(A) -> exitScene(A) -> enterScene(B) -> exitScene(B). The following example shows the scenario if the APIs are not called in pairs:
enterScene(A) --> The custom scenario is A.
enterScene(B) --> The custom scenario is B.
enterScene(C) --> The custom scenario is C.
exitScene(B) --> The custom scenario is C.
exitScene(C) --> The custom scenario is empty.
exitScene(A) --> The custom scenario is empty.
If sceneName is empty, the API returns immediately.

Adding and Removing a Custom Data Collector (Performance Monitoring)

The configuration method for the performance monitoring module is different from that for the crash monitoring module. The custom data for the performance monitoring module includes custom dimensions and custom fields.
Custom dimensions: These are three sets of keys (for more information, see ICustomDataEditor) specified by the SDK, with 10 keys per set. The application can select appropriate keys to report data. In the console, you can set aliases for these keys for viewing and analysis. For custom dimensions, the server stores them as separate fields. This enables rich query and analysis capabilities. Currently, global settings or callback settings before data reporting are supported. You can obtain the global API via Bugly.getGlobalCustomDataEditor to set custom dimensions, or use metric callbacks (ICustomDataCollector) or issue callbacks (ICustomDataCollectorForIssue) to configure or update custom dimensions.
Custom fields: These involve keys and values freely configured by the application. The SDK does not interpret the field types and stores them as strings. In the console, you can query reports containing specific content via custom fields in the issue list and issue details. You can only configure custom fields via the issue callback ICustomDataCollectorForIssue.

Global Settings

Global settings mean the application can call the global setting API at any time to configure custom dimensions. For the same key, repeated settings update its existing value. During performance reporting, the globally cached custom dimension data is obtained.
You can use the following API to obtain the default global custom dimension collection callback and configure global custom dimensions.
/**
* Obtains the global custom dimension setting API.
* @return Global custom dimension setting class.
*/
public static ICustomDataEditor getGlobalCustomDataEditor();

// Configuration example
ICustomDataEditor customDataEditor = Bugly.getGlobalCustomDataEditor();
customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());

Callback Settings

Callback settings mean the application configures callbacks. Before detected issues are reported, the API callback of the application is triggered to collect additional contextual information based on the specific issue and scenario. Callback settings are categorized into metric callbacks and issue callbacks.
// Adds a callback. Metric callbacks and issue callbacks need to be configured separately.
Bugly.addCustomDataCollector(customDataEditor);

// Removes a callback. Metric callbacks and issue callbacks need to be removed separately.
Bugly.removeCustomDataCollector(customDataDditor);

Metric callbacks
: ICustomDataCollector. For example, lag metric and memory peak callbacks are metric callbacks. These callbacks are triggered before information collection and data caching, allowing the application to add additional information if needed.
/**
* Configures a metric data callback. Multiple callbacks can be configured for different monitoring items and scenarios.
* @param dataCollector Global custom data callback class.
*/
public static void addCustomDataCollector(ICustomDataCollector dataCollector);
/**
* Removes a global custom data callback.
* @param dataCollector Global custom data callback class.
*/
public static void removeCustomDataCollector(ICustomDataCollector dataCollector);

// Configuration example
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());
}
};

// Configures the metric callback.
Bugly.addCustomDataCollector(customDataEditor);
// Removes the metric callback.
Bugly.removeCustomDataCollector(customDataDditor);
Issue callbacks: ICustomDataCollectorForIssue. For example, lag monitoring, Java memory leak, and large image analysis callbacks are issue callbacks. These callbacks are triggered when abnormal issues are detected, allowing you to add additional information if needed.
/**
* Configures a single-metric issue custom data callback. Multiple callbacks can be configured for different monitoring items and scenarios.
* @param issueDataCollector Single-metric issue custom data callback class.
*/
public static void addCustomDataCollector(ICustomDataCollectorForIssue issueDataCollector);
/**
* Removes a single-metric issue custom data callback.
* @param issueDataCollector Single-metric issue custom data callback class.
*/
public static void removeCustomDataCollector(ICustomDataCollectorForIssue issueDataCollector);

// Configuration example
ICustomDataCollectorForIssue issueDataCollector = new ICustomDataCollectorForIssue() {
@Override
public void collectCustomData(String pluginName, String scene, ICustomDataEditorForIssue customDataEditor) {
// Allows overriding global custom dimension settings.
customDataEditor.putStringParam(ICustomDataEditor.STRING_PARAM_1, getAppStateDesc());
customDataEditor.putNumberParam(ICustomDataEditor.NUMBER_PARAM_1, Debug.getPss());
}
}
// Configures the issue callback.
Bugly.addCustomDataCollector(issueDataCollector);
// Removes the issue callback.
Bugly.removeCustomDataCollector(issueDataCollector);

Dynamic Switches

If you need to dynamically enable or disable certain crash monitoring or performance monitoring items of RUM Pro in specific scenarios, you can use the following APIs. However, the dynamic crash switches should be used only when necessary, as they may result in missed exception reports.
/**
* Dynamic switch for crash monitoring.
* @param crashType Crash type. Valid values: Bugly.JAVA_CRASH, Bugly.NATIVE_CRASH, and Bugly.ANR_CRASH.
* @param isAble Set to true to enable monitoring, or false to disable monitoring.
*/
public static void setCrashMonitorAble(@CrashTypeKey int crashType, boolean isAble);

/**
* Dynamic switch for performance monitoring (enable or disable a group of monitoring items).
* @param monitorList List of monitoring items, which can be obtained from BuglyMonitorName.
* @param isAble Set to true to enable monitoring, or false to disable monitoring.
*/
public static void setPerformanceMonitorsAble(List<String> monitorList, boolean isAble);

/**
* Dynamic switch for performance monitoring (enable or disable a single monitoring item).
* @param monitorName Monitoring item.
* @param isAble Set to true to enable monitoring, or false to disable monitoring.
*/
public static void setPerformanceMonitorAble(String monitorName, boolean isAble);

/**
* Disables all performance monitoring items.
*/
public static void abolishPerformanceMonitors();

Startup Monitoring

By default, startup monitoring considers the end of the first frame rendering of the first Activity as the startup completion point. You can also use the reportAppFullLaunch API to specify a custom startup completion point in the application. Additionally, AppLaunch provides APIs for adding custom tags and custom tracking spans.
AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.reportAppFullLaunch();
Custom tags: You can add custom tags to the startup data for subsequent drill-down analysis, as shown below:
AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.addTag("show_splash");
Custom tracking spans: You can use spans to monitor time-consuming tasks during the startup process.
AppLaunch appLaunch = AppLaunchProxy.getAppLaunch();
appLaunch.spanStart("login", null); // Login task begins.
....
appLaunch.spanStart("verification_code", "login"); // Verification code task begins.
....
appLaunch.spanEnd("verification_code"); // Verification code task ends.
....
appLaunch.spanEnd("login"); // Login task ends.
Detailed description of the AppLaunch API:
public interface AppLaunch {
/**
* Starts startup monitoring.
* @param context Context
*/
void install(Context context);

/**
* Adds a custom tag.
* @param tag Custom tag.
*/
void addTag(String tag);

/**
* Starts a tracking span.
* @param spanName Name of the tracking span to be started.
* @param parentSpanName Name of the parent span for the current tracking span.
*/
void spanStart(String spanName, String parentSpanName);

/**
* Ends a tracking span.
* @param spanName Name of the tracking span to be ended.
*/
void spanEnd(String spanName);

/**
* Marks startup completion.
*/
void reportAppFullLaunch();
}





Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback