btrace

README 中文版

btrace for Android

btrace for iOS

btrace for HarmonyOS

Major Update

We are proud to announce the launch of btrace 3.0, introducing an industry-first high-performance synchronized sampling-based tracing solution. Additionally, the new version now provides comprehensive iOS tracing capabilities. We have also extended btrace to HarmonyOS, providing on-device SDK and command-line tooling to capture trace data and quickly locate performance issues for HarmonyOS apps.

btrace for Android

Integration

Add dependencies in app/build.gradle file:

dependencies {
    if (enable_btrace == 'true') {
        implementation 'com.bytedance.btrace:rhea-inhouse:3.0.0'
    } else {
        implementation 'com.bytedance.btrace:rhea-inhouse-noop:3.0.0'
    }
}

Add enable_btrace switch in the gradle.properties file:

# Turn on this switch when you want to build app that support tracing.
enable_btrace=false

Add initialization code in attachBaseContext() method of your Application:

public class MyApp extends Application {

    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        // When rhea-inhouse-noop is used, RheaTrace3.init() has empty implementation.
        RheaTrace3.init(base);
    }
}

Usage

To use btrace 3.0, follow these instructions:

1. Make sure that your computer has integrated adb and Java and Python3 environment.
2. Connect your phone to your computer and make sure it can recognized by adb devices.
3. Install the APK that integrates btrace 3.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_package_name} -t 10 -o output.pb -r sched

6. Open the generated trace file in https://ui.perfetto.dev/ for detailed analysis.

Script Management

Version	Release Date	jar	Release Notes
3.0.0	2025-06-10	rhea-trace-shell-3.0.0.jar	3.0 first release

Parameters Description

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	${applicationName}_yyyy_MM_dd_HH_mm_ss.pb	Specifies the path where the trace artifact is saved. By default, the value is autogenerated based on the tracing app package name and current timestamp.
-t $timeInSecond	5	Specifies the duration of the tracing, in seconds. Note that: On MacOS, interactive tracing mode will be activated if you don’t specifying the tracing duration. On windows, tracing dration must be specified, because we don’t support interactive tracing mode on Windows currently.
-m $mappingPath		Specifies the mapping file path for the abofuscated app. Note that: it’s not the methodMapping file that was used in btrace 2.0, but the mapping file generated by proguard. There is no methodMapping file in btrace 3.0.
-mode $mode	Decided at runtime.	btrace currently support two kinds of modes: perfetto: The default mode for systems 8.1 and above, allowing collecting system atrace and ftrace using perfetto service besides the app trace. simple: The default mode for systems below 8.1, allowin collecting app trace only.
-maxAppTraceBufferSize $size	200000	Specifies the maximum count of stacktraces that our buffer allows to save, previously saved stacktraces will be overwritten if the maximum limit is met.
-sampleInterval $ns	1000000	Specifies the minimum sampling backtracing interval in nanoseconds.
-waitTraceTimeout	20	Specifies the timeout seconds for waiting for tracing data writing to complete and being pulled to the PC.
-s $serial		Specifies the device connected by adb.
-r		Automatically restarts the app to tracing the start up stage.
–list		Displays a list of supported atrace categories for the device.

Known Issues

	Problems	Advices
1	We currently only support devices running Android 8.0 or higher.	Please use devices with Android 8.0 or higher.
2	Java object allocation monitoring is not yet adapted for devices with Android 15 and above.	If you need to inspect object memory allocation information or require more detailed tracing, please use devices with Android versions below 15.
3	Devices that do not support Perfetto (mostly systems before 8.1) cannot collect system information such as CPU scheduling.	Try with -mode simple.
4	32-bit devices or applications cannot collect tracing data.	Please install and use 64-bit applications on 64-bit devices.

btrace for iOS

Record trace data offline without Instruments to help find performance issue of your app.

Installation

Clone source code, and add the following lines to your Podfile:

pod 'BTrace', :subspecs => ['Core', 'Debug'], :path => 'xxx/btrace-iOS'
pod 'fishhook', :git => 'https://github.com/facebook/fishhook.git', :branch => 'main'

Install command line tool:

# using homebrew
brew install libusbmuxd
brew install poetry

# install from the BTraceTool directory
poetry install

Usage

Activate the virtual environment before executing commands.

# activate from the BTraceTool directory
poetry shell
# or 
poetry env activate

Record

Note that if ‘-l’ is not specified, app must have been launched before recording.

python3 -m btrace record [-h] [-i DEVICE_ID] [-b BUNDLE_ID] [-o OUTPUT] [-t TIME_LIMIT] [-d DSYM_PATH] [-m] [-l] [-s]

Options

Option	Description
-h, –help	Show help
-i DEVICE_ID, –device_id DEVICE_ID	Device id. If not specified: · If only one device is connected to Mac, it will be chosen · If multiple devices are connected to Mac, prompt the user to make a selection
-b BUNDLE_ID –bundle_id BUNDLE_ID	Bundle id
-o OUTPUT –output OUTPUT	Output path. If not specified, data will be saved to ‘~/Desktop/btrace’
-t TIME_LIMIT –time_limit TIME_LIMIT	Limit recording time, default 3600s
-d DSYM_PATH –dsym_path DSYM_PATH	Dsym file path, or app path built by Xcode in debug mode. If specified，flamegraph will be displayed automatically after the recording ends
-m –main_thread_only	If given, only record main thread trace data
-l –launch	If given, app will be launched/relaunched, and start recording on app launch
-s –sys_symbol	If given, symbols in the system libraries will be parsed

Examples

python3 -m btrace record -i xxx -b xxx -d /xxxDebug-iphoneos/xxx.app
python3 -m btrace record -i xxx -b xxx -d /xxxDebug-iphoneos/xxx.dSYM

Stop

ctrl + c

Parse

When should the ‘parse’ command used?

• ‘-d’ option is not specified in the ‘record’ command.
• reopen the parsed data

python3 -m btrace parse [-h] [-d DSYM_PATH] [-f] [-s] file_path

Options

Option	Description
-h, –help	Show help
-d DSYM_PATH, –dsym_path DSYM_PATH	Dsym file path, or app path built by Xcode in debug mode
-s, –sys_symbol	If given, symbols in the system libraries will be parsed
-f, –force	If given, force re-parsing trace data

Examples

btrace parse -d /xxx.dSYM xxx.sqlite
btrace parse -d /xxx.app xxx.sqlite

btrace for HarmonyOS

Record trace data for HarmonyOS apps to help find performance issues.

Integration

Add the on-device SDK to your HarmonyOS project via ohpm:

ohpm install @bytedance/btrace

Initialize the offline server as early as possible during app startup:

import { OfflineServer } from '@bytedance/btrace'

OfflineServer.Init()

Command-Line Tool Installation

Prerequisites

• JDK 11 or above is required, with environment variables configured properly.
• The hdc tool is required to operate apps on the device. Add it to your PATH:

export PATH="/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH"

• Parsing native symbols requires llvm-addr2line. Add it to your PATH:

export PATH="/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin:$PATH"

Install

1. Download the latest harmony-trace-cli jar and place it under ~/.oh_trace_cli directory.

Note: The download artifacts will be published with the official release. Please stay tuned.

Usage

Run the following command in the directory where harmony-trace-cli.jar is located:

java -jar harmony-trace-cli.jar -b ${your_bundle_name} -t 10

The above command starts tracing for the given bundle from its current foreground page, samples all threads for 10 seconds, saves the result to the current directory and automatically generates a flame graph.

Stop

ctrl + c

Stops the tracing and automatically exports the trace file from the app sandbox.

Parameters Description

Required Parameters

Parameter	Default Value	Description
-b, –bundle_name $bundleName	N/A	Specifies the bundle name of your app.

Optional Parameters

Parameter	Default Value	Description
-h, –help		Show help.
-k, –key $deviceKey		Specifies the device connected by hdc. If only one device is connected, it will be chosen automatically. If multiple devices are connected, prompt the user to make a selection.
-o, –output_path $outputPath	~/Desktop/ohtrace	Specifies the path where the trace artifact is saved.
-t, –time_limit $timeLimit	60	Specifies the maximum tracing duration in seconds. Tracing will stop automatically when the duration is reached.
-N, –native_path $nativePath		Absolute path to the directory containing native .so files for symbolication.
-s, –source_mapping $sourceMapping		Absolute path to the sourceMap file.
-n, –name_cache $nameCache		Absolute path to the NameCache file.
-i, –sample_interval $sampleInterval		Sampling interval. In normal mode: unit is ms, minimum is 1ms. In high-frequency mode: unit is us, minimum is 50us.
-H, –high_freq		Enable high-frequency sampling mode.
-S, –buffer_size $bufferSize		Specifies how many call stack samples can be stored.
-m, –main_only		Only collect call stacks of the main thread.
-r, –restart		Launch / relaunch the app and start tracing from the launch stage.
-sp, –skip_perfetto		Skip generating the flame graph via Perfetto after the trace is exported.
-a, –all_symbol		Display all symbols including system symbols (system symbols are hidden by default).

Known Issues

• CLI is currently macOS-only: the harmony-trace-cli command-line tool only supports macOS at the moment; Windows / Linux support will be added in future releases.
• On-device symbol resolution can be slow: the SDK currently performs symbol resolution on-device, which is relatively time-consuming. After the trace capture finishes, exporting from the device and writing to disk may take noticeably longer; we will continue to optimize this.
• System library symbols must be supplied manually: the SDK cannot currently resolve symbols of HarmonyOS system libraries on-device. To recover the symbols, users need to supply the directory containing the matching .so files via -N, --native_path, and the CLI tool will perform symbolication offline.

Technology Principle

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

Feedback

We’ve made a lot of improvements in btrace 3.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