Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bytedance/btrace
π₯π₯ btrace(AKA RheaTrace) is a high performance Android trace tool which is based on Perfetto, it support to define custom events automatically during building apk and using bhook to provider more native events like Render/Binder/IO etc.
https://github.com/bytedance/btrace
Last synced: about 2 hours ago
JSON representation
π₯π₯ btrace(AKA RheaTrace) is a high performance Android trace tool which is based on Perfetto, it support to define custom events automatically during building apk and using bhook to provider more native events like Render/Binder/IO etc.
- Host: GitHub
- URL: https://github.com/bytedance/btrace
- Owner: bytedance
- License: other
- Created: 2021-12-17T12:01:54.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-18T05:22:27.000Z (about 1 year ago)
- Last Synced: 2024-08-01T22:48:17.975Z (3 months ago)
- Language: Kotlin
- Homepage:
- Size: 7.99 MB
- Stars: 1,869
- Watchers: 39
- Forks: 267
- Open Issues: 40
-
Metadata Files:
- Readme: README.MD
- Contributing: CONTRIBUTING.MD
- License: LICENSE
Awesome Lists containing this project
- MobileHackersWeapons - btrace
README
# btrace
[README δΈζη](./README.zh-CN.md)
## 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:
``` js
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.
``` js
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 = ""
}
}
```
### 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](GRADLE_CONFIG.MD)|
|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.
```shell
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](https://oss.sonatype.org/service/local/repositories/releases/content/com/bytedance/btrace/rhea-trace-processor/2.0.0/rhea-trace-processor-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||Specifies the package name of your app|
#### 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.|
|-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.||
## 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!](INTRODUCTION.MD) .
## 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. |
## 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](./CONTRIBUTING.MD)
## License
[Apache License](./LICENSE)