Prerequisites
Crash, ANR, and OOM data is 100% reported, is enabled by default, and does not support sampling. All other monitoring items are disabled by default and support sampling. Generally, performance metric monitoring is enabled by default, while abnormal performance monitoring is disabled by default. You can adjust these settings through SDK configuration. During integration, please make sure the enabled features meet your expectations.
During integration, it is recommended to set the sampling rate of all monitoring items to 1.0 (sample_ratio and event_sample_ratio) for easier data reporting verification. After the integration is complete, you can change the sampling rate as needed. Alternatively, you can create multiple configuration tasks based on the version type (corresponding to the initialized BuglyBuilder#appVersionType) to configure development tasks, grayscale release tasks, and production tasks. You can enable all monitoring items for development tasks, apply sampling as needed during the grayscale phase, and reduce sampling for the official release as required.
Check whether you have an active resource package for the integrated product as described in the Purchase Instructions. If the product is not bound to an active resource package, data cannot be reported. Crash Monitoring
Crash monitoring captures runtime exceptions and errors (such as Java exceptions or native crashes) and collects crash logs and stack traces to help developers locate and fix issues, enhancing application stability.
Simulating an Exception
After initialization, you can simulate Java exceptions or native exceptions to verify the reporting feature of the SDK.
After a crash occurs, certain exceptions are reported after a restart. To ensure the current crash handling is completed, it is recommended to wait for more than 10 seconds after the crash to initiate the restart. Reporting may be delayed. During testing, it is recommended to manually trigger the simulation multiple times before you refresh the page.
Bugly.testCrash(Bugly.JAVA_CRASH);
Bugly.testCrash(Bugly.NATIVE_CRASH);
Checking Data Reporting
ANR Monitoring
Android ANR monitoring detects when the application's main thread becomes unresponsive for an extended period (such as failing to process input events within 5 seconds). It records and reports the relevant stack trace information to help developers locate and optimize lag issues.
Simulating an Exception
Similar to crashes, you can simulate an ANR either by using the test API provided by Terminal Performance Monitoring Pro (RUM Pro), or you can manually execute a time-consuming task on the UI thread.
Simulate an ANR with the API.
Bugly.testCrash(Bugly.ANR_CRASH);
Execute the following time-consuming logic on the UI thread to trigger an ANR.
private void testANR(){
try {
Thread.sleep(30000);
} catch (Exception e){
}
}
Checking Data Reporting
Error Monitoring
Errors generally refer to user-defined exceptions, such as caught Java exceptions, C# exceptions, JavaScript exceptions, and Lua exceptions. They are typically reported via handleCatchException or postException in RUM Pro (for details, see the Other APIs, Reporting a Custom Exception, or Reporting a Caught Java Exception section).
Checking the SDK Configuration
SDK Integration
The application can report custom errors through the handleCatchException and postException APIs provided by RUM Pro.
To report a caught Java exception, see the following sample code.
private void testJavaCatchError(){
String content = "a illegal string.";
try {
JSONObject jsonObject = new JSONObject(content);
double price = jsonObject.getDouble("price");
} catch (Throwable t) {
Bugly.handleCatchException(Thread.currentThread(), t,
"in test code for json parse fail.", content.getBytes(), true);
}
}
To report a custom exception, see the following sample code.
Bugly.postException(4, "testErrorType", "testErrorMsg", "testStack", null);
Checking Data Reporting
Startup Monitoring
When startup monitoring is enabled, the startup module automatically installs the monitoring feature and reports startup data after SDK initialization. You can customize the startup completion point via the Bugly.reportAppFullLaunch API. Startup monitoring also supports custom tags and tracking APIs to monitor time-consuming tasks during the startup process.
Checking the SDK Configuration
SDK Integration
private void costJobOne() {
AppLaunchProxy.getAppLaunch().addTag("has_cost_job_one");
AppLaunchProxy.getAppLaunch().spanStart("costJobOne", null);
try {
Thread.sleep(300);
} catch (Throwable t) {
Bugly.handleCatchException(Thread.currentThread(), t, "costJobOne sleep fail", null, true);
}
AppLaunchProxy.getAppLaunch().spanEnd("costJobOne");
}
private void finalJob() {
AppLaunchProxy.getAppLaunch().reportAppFullLaunch();
}
Checking Data Reporting
Lag Monitoring
Application lag is a major cause of user churn. The lag monitoring module is designed to help you address lag issues. A key approach to lag mitigation involves using effective metrics to assess the current state of the application and capturing sufficient information to provide optimization guidance. The module evaluates application smoothness through two metrics: frames per second (FPS) and suspension rate. By monitoring lag issues and directly capturing lag stacks, it helps pinpoint the root causes of lag issues and provides clear optimization guidance.
Lag metric uses stable and lightweight collection techniques to collect smoothness data throughout the entire application runtime.
Lag issue monitoring utilizes high-frequency stack trace capturing to provide rich contextual information for accurate cause analysis.
The self-developed fast stack trace capturing technology for the Android platform achieves a 6 times performance improvement compared to traditional stack trace capturing methods.
Both lag metrics and lag issues support custom sampling rates and provide robust data analysis capabilities.
Checking the SDK Configuration
Lag
When the lag metric ("looper_metric") is enabled, the SDK monitors application smoothness after initialization. During a single application run, data is first collected and stored locally, then aggregated and reported during the next startup. To avoid impacting application startup performance, the SDK aggregates and reports the cached data to the backend 5 minutes after initialization.
FPS: frame rate. It refers to the number of images the GPU and CPU can produce during application runtime, measured in frames per second (FPS). It is typically used as a metric to evaluate hardware performance and application smoothness.
Suspension rate: If the refresh delay between two application frames exceeds 200 ms, it is considered that the application has poor responsiveness to user interactions, and this delay is added to the suspension time. The suspension rate of a device is its total suspension time divided by the total foreground duration in a day, measured in seconds per hour.
Lag
After lag monitoring ("looper_stack") is enabled, if time-consuming logic executed on the UI thread exceeds 500 ms, lag reporting is triggered. Lag monitoring detects UI thread lag by monitoring message execution on the UI thread.
During the verification phase, it is recommended to set both the "event_sample_ratio" (message sampling rate) and "sample_ratio" (device sampling rate) for lag monitoring to 1. This ensures that lag reporting is triggered when the drolagp threshold is met.
Simulating an Exception
To simulate lag reporting, see the following sample code.
private void testLongLag() {
showToast("Long lag testing");
sleep(200);
callFunctionA();
callFunctionB();
}
private void callFunctionA() {
sleep(400);
callFunctionB();
}
private void callFunctionB() {
sleep(300);
}
private static void sleep(long timeInMs) {
try {
Thread.sleep(timeInMs);
} catch (Throwable t) {
Bugly.handleCatchException(Thread.currentThread(), t, "sleep", null, false);
}
}
Checking Data Reporting
Memory Monitoring
Memory monitoring supports the memory peak and memory details features, with more memory monitoring features under development.
Memory Peak
Memory peak refers to the highest memory usage of the application during its entire runtime. RUM Pro queries the application's memory usage through scheduled tasks, records the maximum usage throughout the runtime, and reports it after the next application startup.
Physical memory peak: peak physical memory used by the application during a single run, also known as peak physical set size (PSS).
Virtual memory peak: peak virtual memory used by the application during a single run, also known as peak virtual set size (VSS).
Java heap memory peak: peak Java heap memory used by the application during a single run.
Memory Details
During SDK initialization, you need to configure the monitoring item BuglyMonitorName.MEMORY_JAVA_CEILING in BuglyBuilder.
public static void initBugly(Context context) {
String appID = "xxxxxxx";
String appKey = "xxxxxxxxxxx";
BuglyBuilder builder = new BuglyBuilder(appID, appKey);
......
build.addMonitor(BuglyMonitorName.MEMORY_JAVA_CEILING);
Bugly.init(context, builder);
}
sample_ratio: controls the user sampling rate, which is the percentage of devices to enable this feature.
event_sample_ratio: controls the event sampling rate, which determines whether an issue is reported when the memory limit is reached.
threshold: sets the trigger for dumping heap dump files. 90 means dumping starts when 90% of the maximum value is reached. The maximum heap memory corresponds to Runtime.getRuntime().maxMemory().
Checking Data Reporting
Network Monitoring
Network monitoring uses the EventListener of OkHttp3 to monitor the quality of HTTP requests, including request duration, success rate, data transfer volume, and key phase duration of the request. The following capabilities are implemented through an instrumentation-free approach:
1. You can follow the SDK integration guide and use the OkHttpClient created by using BuglyListenerFactory to monitor the quality of HTTP and HTTPS requests.
2. BuglyURLStreamHandlerFactory is provided as a proxy for the system's native HttpURLConnection to monitor HTTP and HTTPS requests implemented using the system's native APIs.
Note:
The following scenarios are not supported:
HTTP requests not implemented using native APIs or OkHttp3.
The component uses the OkHttp3 library to implement HTTP requests but the OkHttpClient process is not modified, meaning that BuglyListenerFactory is not used as the EventListener.Factory for OkHttpClient.
Checking the SDK Configuration
Network monitoring includes the following configuration properties:
sample_ratio: device sampling rate, which is the percentage of devices to enable network monitoring.
daily_report_limit: specifies the maximum number of times network monitoring data can be reported per day. Network monitoring data is reported in batches. The specific batching logic is determined by max_batch_count and min_batch_count.
max_batch_count: specifies the maximum number of HTTP request quality data entries contained in a single network monitoring data report. The default value is 100.
min_batch_count: specifies the minimum number of HTTP request quality data entries contained in a single network monitoring data report. The default value is 50.
Note:
During the testing phase, it is recommended to set sample_ratio to 1. After testing, you can change the device sampling rate based on actual needs.
During the testing phase, it is recommended to set min_batch_count to 5 or 10 for faster data reporting to the backend. After testing, you can change the value based on your business needs or restore it to the default value.
SDK Integration
1. Enable proxy for the system's native HttpURLConnection. If you do not want to enable proxy for HTTP requests using the system's native APIs, you can skip this step.
If you want to enable proxy for HTTP requests that use the system's native APIs, it is recommended to enable proxy as early as possible in Application#onCreate.
BuglyURLStreamHandlerFactory.init(okHttpClient);
After the proxy is enabled, you can use the following code to disable it.
BuglyURLStreamHandlerFactory.reset();
2. Use BuglyListenerFactory to create an OkHttpClient.
OkHttpClient client = new OkHttpClient.Builder()
.eventListenerFactory(BuglyListenerFactory.getInstance())
.build();
Checking Data Reporting
Traffic Monitoring
The core feature of traffic monitoring is its ability to track application data usage in real time. Through real-time monitoring, you can stay informed about data consumption patterns and promptly identify issues such as unexpected traffic usage. This helps you avoid exceeding data plans or incurring additional charges. Additionally, traffic monitoring assists in optimizing application power consumption and reducing unnecessary data requests to deliver a more efficient user experience and extend the battery life. This feature also enables drilling down to the domain level, allowing you to identify which domains or services consume a large amount of traffic, facilitating targeted measures to optimize data transmission.
Checking the SDK Configuration
Before you verify the data reporting feature, please check the traffic monitoring configuration in Setting > SDK Configuration. Traffic monitoring includes two configuration items: Traffic--10-minute traffic and Traffic--per-process traffic. SDK Integration
To enable the traffic monitoring feature, you need to execute the following statements during SDK initialization, and enable traffic monitoring in the backend.
...
buglyBuilder.addMonitor(BuglyMonitorName.TRAFFIC);
buglyBuilder.addMonitor(BuglyMonitorName.TRAFFIC_DETAIL);
...
Bugly.init(application, buglyBuilder);
The SDK also provides APIs for reporting custom scenario traffic.
CustomTrafficStatistic.getInstance().addHttpToQueue(SocketInfo socketInfo);
SocketInfo contains many other fields. To collect traffic statistics, you need to assign values only to the following fields. Other member variables can be ignored.
class SocketInfo {
receivedBytes;
sendBytes;
networkType;
frontState;
host;
startTimeStamp;
......
}
Checking Data Reporting
Page Performance
User experience (UX) is a critical factor in mobile application development. With the advancement in smartphone hardware performance and the continuous increase in user demands, users have higher expectations for application responsiveness and smoothness. Page startup time is a key metric for user experience, especially for mobile applications. An extended page startup time can frustrate users and may even result in user churn.
RUM Pro monitors the cold start time of Activities by default. The start time is divided into page rendering time and page loading time.
Page rendering time: This is the duration from the call of Activity's onCreate to the completion of the first frame rendering.
Page loading time: This is the same as the page rendering time by default. You can customize the loading end time of the Activity through the reportActivityFullLaunch API.
Checking the SDK Configuration
sample_ratio: controls the user sampling rate, which is the percentage of devices to enable this feature. 1 indicates the feature is enabled for all devices. 0 indicates the feature is disabled for all devices.
SDK Integration
Before you call the Bugly.init API, add the following code in the client.
...
buglyBuilder.addMonitor(BuglyMonitorName.PAGE_LAUNCH);
...
Bugly.init(context, builder);
In addition to the overall page startup time, you can also call the following APIs to monitor the time consumption of each span during the page startup process. A span is a sub-stage of the page startup process. The following are the APIs of the com.tencent.rmonitor.pagelaunch.PageLaunchMonitor class, which is a singleton class. You can obtain the singleton object via PageLaunchMonitor.getInstance().
public void startSpan(Activity activity, String name, String parentName);
public void endSpan(Activity activity, String name);
public void reportActivityFullLaunch(Activity activity);
Note:
The startSpan and endSpan methods must be called in pairs. Only one record is kept for spans with the same name. A later span with the same name will overwrite the previous one.
See the following sample code:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
PageLaunchMonitor.getInstance().startSpan(this, "MemoryTracerTest", "");
PageLaunchMonitor.getInstance().startSpan(this, "onCreate", "MemoryTracerTest");
startMemoryTrace();
PageLaunchMonitor.getInstance().endSpan(this, "onCreate");
}
@Override
public void onResume() {
super.onResume();
PageLaunchMonitor.getInstance().startSpan(this, "onResume", "MemoryTracerTest");
reStartMemoryTrace();
PageLaunchMonitor.getInstance().endSpan(this, "onResume");
PageLaunchMonitor.getInstance().endSpan(this, "MemoryTracerTest");
new Thread (new Runnable() {
reportLaunchFinished();
}).start();
}
private void reportLaunchFinished() {
PageLaunchMonitor.getInstance().reportActivityFullLaunch(this);
}
Checking Data Reporting