Add rhea-gradle-plugin as a dependency in the build.gradle file in the root directory of your project:
buildscript {
dependencies {
classpath 'com.bytedance.btrace:rhea-gradle-plugin:2.0.3-rc02'
}
}
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.3-rc02"
}
...
apply plugin: 'com.bytedance.rhea-trace'
...
rheaTrace {
compilation {
traceFilterFilePath = "${project.rootDir}/trace-filter/traceFilter.txt"
needPackageWithMethodMap = true
applyMethodMappingFilePath = ""
}
}
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. |
To use RheaTrace 2.0, follow these instructions:
java -jar rhea-trace-shell.jar -a ${your app package name} -t 10 -o output.pb -r rhea.all sched -fullClassName
Version | Release Date | Download | Release Notes |
---|---|---|---|
2.0.0 | 2023-06-24 | rhea-trace-shell-2.0.0.jar | 2.0.0 first release |
The following table describes the parameters for RheaTrace 2.0 command-line arguments:
Parameter | Default Value | Description |
---|---|---|
-a $applicationName | N/A | Specifies the package name of your app |
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. | |
-deeplink $deeplink | N/A | Specifies the deeplink. |
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. |
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! .
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 |
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. |
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!