btrace

README 中文版

Major Update

1. User Experience: We now support Windows! No more dependency on Python 2.7 and storage permissions! The scripting language has been changed to Java reducing the interruption caused by the usability issue of the scripting tool to almost zero! And we've switched to the PB protocol for trace artifacts, resulting in a 70% reduction in storage needs and a 7x speed boost when opening trace files.
2. Performance Experience: Rewriting the method Trace collection logic, switching data from strings to integers, reducing memory usage by 80%. Data storage is changed to mmap mode, optimizing lock-free queue logic, providing accurate instrumentation strategies, and further reducing performance loss to 15% under millions of methods instrumentation!
3. Monitoring Data: Adding 4 new data monitoring capabilities, including detailed data on Rendering, Binder, thread creation, and Wait/Notify/Park/Unpark!

Integration

Project Configuration

Add rhea-gradle-plugin as a dependency in the build.gradle file in the root directory of your project:

buildscript {
    repositories {
        ...
        maven {
            url "https://artifact.bytedance.com/repository/byteX/"
        }
        ...
    }
    dependencies {
        classpath 'com.bytedance.btrace:rhea-gradle-plugin:2.0.0'
    }
}

allprojects {
    repositories {
        ...
        maven {
            url "https://artifact.bytedance.com/repository/byteX/"
        }
        ...
    }
}

Then, apply the following plugins and dependencies to the app/build.gradle file.

dependencies {
    // rheatrace core lib
    implementation "com.bytedance.btrace:rhea-core:2.0.0"

}
...
apply plugin: 'com.bytedance.rhea-trace'
...
rheaTrace {
   compilation {
      traceFilterFilePath = "${project.rootDir}/trace-filter/traceFilter.txt"
      needPackageWithMethodMap = true
      applyMethodMappingFilePath = ""
   }
}

Plugin Configuration

RheaTrace 2.0 simplifies the compilation plugin configutation, requiring only a compilation configuration to control the behavior during compilation. The runtime configuration in RheaTrace 1.0 is deprecated, but to ensure compatibility when upgrading, we still keep the runtime parameter configuration, even though it does not affect behavior. Instead, in RheaTrace 2.0, dynamic configuration is achieved through command-line arguments in the script, which will be described in detail later.

Parameter	Default Value	Description
traceFilterFilePath	null	This file determines which methods need to be instrumented, and its usage is consistent with RheaTrace 1.0. Please refer to：RheaTrace Gradle Plugin Configuration
applyMethodMappingFilePath	null	The method ID of the device can be specified by specifying the methodMapping.txt file path output from the last compilation to ensure that the method IDs of multiple compilations are consistent.
needPackageWithMethodMap	true	Whether to package the methodMapping.txt file inside the apk.

Usage

To use RheaTrace 2.0, follow these instructions:

1. Ensure that your computer has integrated adb and Java environment.
2. Connect your phone to your computer and ensure it is recognized by adb devices.
3. Install the APK that integrates RheaTrace 2.0 on your phone.
4. Download the latest script from "Script Management" below to your computer.
5. In the directory where the computer script is located, execute the following command.

java -jar rhea-trace-shell.jar -a ${your app package name} -t 10 -o output.pb -r rhea.all sched -fullClassName

6. The trace artifact can be analyzed by https://ui.perfetto.dev/ for analysis.

Script Management

Version	Release Date	Download	Release Notes
2.0.0	2023-06-24	rhea-trace-shell-2.0.0.jar	2.0.0 first release

Parameter Description

The following table describes the parameters for RheaTrace 2.0 command-line arguments:

Required Parameters

Parameter	Default Value	Description
-a $applicationName	N/A

Optional Parameters

Parameter	Default Value	Description
-o $outputPath	N/A	Specifies the path where the trace artifact is saved. By default, the value is autogenerated based on the timestamp.
-t $timeInSecond	5	Specifies the duration of the tracing period, in seconds.
-mode $mode	By device	Specifies the tracing mode. Two modes are currently supported:1. perfetto: The default mode for systems 8.1 and above, allowing trace collection for your application functions as well as system atrace and ftrace.2. simple: The default mode for systems below 8.1, allowing trace collection for your application functions as well as system atrace.
-maxAppTraceBufferSize $size	500000000	Specifies the buffer size used during trace collection, in bytes. Generally, this parameter does not need to be configured unless you encounter a prompt similar to the following:MaxAppTraceBufferSize is too small. Expected 100515704 Actual 100000000. Add -maxAppTraceBufferSize 100515704 to your commandNote: maxAppTraceBufferSize only takes effect during the first trace after App startup.
-threshold $ns	0	Specifies the function time threshold during trace collection, in nanoseconds. This parameter can reduce the size of the tracing artifact when the tracing period is long.
-s $serial		Specifies the device connected by adb.
-mainThreadOnly	N/A	Only traces the main thread.
-r		Automatically restarts the app to capture the startup trace.
-fullClassName		Enabling the package name for trace information.
rhea.binder		Enables binder information enhancement.
rhea.render		Enables rendering monitoring capabilities.
rhea.io		Enables I/O monitoring capabilities.
rhea.thread		Enables thread creation monitoring capabilities.
rhea.block		Enables park/unpark/wait/notify monitoring functions.
rhea.all		Enables all of the above RheaTrace enhanced monitoring capabilities.
-debug		Prints debugging logs.
--list		Displays a list of supported categories for the device.

Technology Principle

If you are interested in the internal details of RheaTrace 2.0, you can refer to the document: RheaTrace 2.0 Internal Principle in Detail! .

Known Issues

No.	Problems	Advice
1	Some custom ROMs may encounter failures in Perfetto trace acquisition, and the error message is as follows: Error: systrace file not found:rheatrace.workspace/systemTrace.trace Tips: your device may not support perfetto. please retry with -mode simple.	1. Try restarting the phone and try again.2. If the problem is not solved, retry with -mode simple.
2	Devices that do not support Perfetto (mostly systems before 8.1) cannot collect system information such as CPU scheduling.	Try with -mode simple.
3	If you're using a 32-bit APK, it can cause crashes due to out-of-memory errors.	To fix this, you can either switch to a 64-bit package, or if you have to use 32-bit, try reducing the virtual memory usage by lowering the bufferSize and configuring the method collection threshold. This will allow you to collect longer traces without using too much virtual memory.
4	If you're having issues with circular dependencies because methodMapping is built into the APK and depends on mergeAssets	You can turn off the built-in methodMapping function. You can do this by setting needPackageWithMethodMap to false in the Gradle plugin configuration. However, if you need to use the btrace function, you'll have to manually provide the path of the methodMapping using the -m option.
5	AGP 7.0+ is not supported yet

Feedback

We've made a lot of improvements in RheaTrace 2.0, including better error prompts. There might still be some cases where the prompts aren't accurate enough or the messages aren't clear. If you run into any issues, just give us a shout in the Lark group below, and we'll do our best to help you out. We always appreciate any other feedback or suggestions you might have too, thanks you!

Contributes

Contributing Guide

License

Apache License