Merge pull request #60 from bytedance/feature/2.0

2.0 release
bytedance · Jun 25, 2023 · ad9e3f1 · ad9e3f1
2 parents 0493394 + adf52a8
commit ad9e3f1
Show file tree

Hide file tree

Showing 461 changed files with 1,220,047 additions and 6,051 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,4 +7,4 @@ local.properties
 **/output
 */.DS_Store
 .DS_Store:
-scripts/python/rheatrace/.build
+scripts/python/rheatrace/.build
diff --git a/GRADLE_CONFIG.MD b/GRADLE_CONFIG.MD
@@ -0,0 +1,87 @@
+## Gradle Build Parameter Description
+
+| Parameter              | Default Value | Description |
+| -------------------------- | ----------------- | ----------------|
+| traceFilterFilePath        | null              | This file configuration determines which methods you don't want to trace. See detailed usage below.|
+| applyMethodMappingFilePath | null              | Set custom event names using a specific method ID, i.e., you can specify the ID value of the method.|
+| needPackageWithMethodMap   | true      | whether the methodMapping will be packaged into the APK during compilation. |
+
+### traceFilterFilePath Configuration Rules
+
+Currently, RheaTrace supports the following:
+
+```
+# Specify which package name clases' methods to instrument.
+-allowpackage rhea/sample/android
+
+# Specify which package name clases' methods to instrument.
+-allowpackage rhea/sample/android
+
+# Instrument methods related to locks.
+-tracesynchronize
+
+# Instrument call points of Native methods.
+-tracenative
+
+# Instrument Aidl methods.
+-traceaidl
+
+# Instrument methods containing loops.
+-traceloop
+
+# Disable instrumentation of time-consuming method calls by default.
+-disabledefaultpreciseinstrumentation
+
+# Enable large method instrumentation, methods with a utility count exceeding 40.
+-tracelargemethod 40
+
+# The caller of this method needs to be instrumented.
+-traceclassmethods rhea.sample.android.app.PreciseInstrumentationTest {
+   test
+}
+
+# Methods annotated with this annotation need to be instrumented.
+-tracemethodannotation org.greenrobot.eventbus.Subscribe
+
+# All methods of this Class will be instrumented.
+-traceclass io.reactivex.internal.observers.LambdaObserver
+
+# The parameter information of this method will be retained in Trace.
+-allowclassmethodswithparametervalues rhea.sample.android.app.RheaApplication {
+   printApplicationName(*java.lang.String);
+}
+```
+
+When `-allowpackage` is configured, `-blockpackage` cannot be set arbitrarily. The package name configured in `-blockpackage` must start with the package name set in `-allowpackage` and must be its subpackage.
+
+For example, in the above case, since `-allowpackage` is set to 'rhea/sample/android', `-blockpackage` can only be set to the subpackage 'rhea/sample/android/test' under 'rhea/sample/android'.
+
+If you need to know the values of certain method parameters during the App's operation, `-allowclassmethodswithparametervalues` can help. As shown in the example above, configure the class name, method name, and method signature, and add an asterisk `*` before the parameter type description you are concerned with. If you are concerned with multiple parameter values, add an asterisk `*` to each. The effect is as follows: the data in the square brackets [rhea.sample.android.app.RheaApplication] represents the value of the parameter.
+
+```
+ .sample.android-23670 [001] ...1 1388264.149291: tracing_mark_write: B|23670|RheaApplication:printApplicationName[rhea.sample.android.app.RheaApplication]
+ .sample.android-23670 [001] ...1 1388264.149391: tracing_mark_write: E|23670|RheaApplication:printApplicationName[rhea.sample.android.app.RheaApplication]
+```
+
+### applyMethodMappingFilePath Configuration Rules
+
+When the `traceWithMethodID` value is set to `true`, a `methodMapping` file will be generated in the `app/build/outputs` directory. The format is as follows:
+
+```
+1,17,rhea.sample.android.app.FirstFragment$onViewCreated$1 onClick (Landroid/view/View;)V
+2,17,rhea.sample.android.app.SecondFragment$onViewCreated$1 onClick (Landroid/view/View;)V
+3,4,rhea.sample.android.app.RheaApplication attachBaseContext (Landroid/content/Context;)V
+4,1,rhea.sample.android.app.FirstFragment onCreateView (Landroid/view/LayoutInflater;Landroid/view/ViewGroup;Landroid/os/Bundle;)Landroid/view/View;
+5,1,rhea.sample.android.app.MainActivity onCreateOptionsMenu (Landroid/view/Menu;)Z
+6,1,rhea.sample.android.app.RheaApplication onCreate ()V
+7,1,rhea.sample.android.app.FirstFragment onViewCreated (Landroid/view/View;Landroid/os/Bundle;)V
+8,1,rhea.sample.android.app.MainActivity onOptionsItemSelected (Landroid/view/MenuItem;)Z
+9,1,rhea.sample.android.app.MainActivity onWindowFocusChanged (Z)V
+10,17,rhea.sample.android.app.MainActivity$onCreate$1 onClick (Landroid/view/View;)V
+11,8,rhea.sample.android.app.MainActivity$onCreate$1 <clinit> ()V
+12,1,rhea.sample.android.app.SecondFragment onCreateView (Landroid/view/LayoutInflater;Landroid/view/ViewGroup;Landroid/os/Bundle;)Landroid/view/View;
+13,1,rhea.sample.android.app.SecondFragment onViewCreated (Landroid/view/View;Landroid/os/Bundle;)V
+1048574,1,android.os.Handler dispatchMessage (Landroid.os.Message;)V
+```
+
+The format is: `Method ID`, `Method accessFlag`, `Class Name`, `Method Name`, `Method Signature`, `Method Return Value`. You can configure the methods with a fixed ID according to the above format.
diff --git a/GRADLE_CONFIG.zh-CN.MD b/GRADLE_CONFIG.zh-CN.MD
@@ -1,68 +1,137 @@
 ## Gradle 构建参数说明
 
-|  参数   | 默认值  | 说明  |
-|  ----  | ----  | ----  |
-| **compilation**  | NA | 与编译相关的配置。 |
-| &nbsp;traceWithMethodID  | fasle | 为 App 中需要跟踪的方法设置 id 以此来跟踪此自定义事件，好处包括减少 APK 包体积增量以及性能提升。 |
-| &nbsp;traceFilterFilePath  | null | 该文件配置决定哪些方法您不希望跟踪，详细用法见下文。|
-| &nbsp;applyMethodMappingFilePath  | null | 用特指定方法 ID 来设置自定义事件名称，即您可以指定方法的 ID 值。|
-| **runtime**  | NA | 与 App 运行相关的配置。 |
-| &nbsp;mainThreadOnly  | fasle | 仅在主线程抓取跟踪事件，如果您仅关心主线程 trace 数据，请将其置为 true。|
-| &nbsp;startWhenAppLaunch  | true | 在 App 启动之初开始抓取跟踪事件，如果您做启动优化，建议将值保持为 true。 |
-| &nbsp;atraceBufferSize  | "100000" | 指定内存存储 atrace 数据 ring buffer 的大小，如果其值过小会导致 trace 数据写入不完整，若您抓取多线程 trace 数据，建议将值设为百万左右量级；最小值为 1 万，最大值为 5 百万。|
+| **参数**                     | **默认值**   | **说明**                                                                                                     |
+| -------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
+| traceFilterFilePath        | null      | 该文件配置决定哪些方法您不希望跟踪，详细用法见下文。                                                                                 |
+| applyMethodMappingFilePath | null      | 用特指定方法 ID 来设置自定义事件名称，即您可以指定方法的 ID 值。                                                                       |
+| needPackageWithMethodMap   | true      | 默认编译时，将产物methodMap一起打进apk                                                                                  |
 
 ### traceFilterFilePath 配置规则
 
 目前 RheaTrace 支持如下。
 
 ```
+# 指定哪些包名下类的方法插桩。
+
 -allowpackage rhea/sample/android
+
+# 指定哪些包名下类的方法不插桩。
+
 -blockpackage rhea/sample/android/test
 
+
+
+# 对锁相关的方法插桩
+
+-tracesynchronize
+
+
+
+# 对Native方法的调用点插桩
+
+-tracenative
+
+
+
+# 对Aidl方法插桩
+
+-traceaidl
+
+
+
+# 对包含循环的方法插桩
+
+-traceloop
+
+
+
+# 关闭默认耗时方法的调用插桩
+
+-disabledefaultpreciseinstrumentation
+
+
+
+# 开启大方法插桩，方法效用数超过40
+
+-tracelargemethod 40
+
+
+
+# 该方法的调用方需要进行插桩
+
+-traceclassmethods rhea.sample.android.app.PreciseInstrumentationTest {
+
+   test
+
+}
+
+
+
+# 被该注解修饰的方法需要被插桩
+
+-tracemethodannotation org.greenrobot.eventbus.Subscribe
+
+
+
+# 该Class的所有方法均会被插桩
+
+-traceclass io.reactivex.internal.observers.LambdaObserver
+
+
+
+# 该方法的参数信息会在Trace中保留
+
 -allowclassmethodswithparametervalues rhea.sample.android.app.RheaApplication {
+
    printApplicationName(*java.lang.String);
-}
 
--blockclassmethods rhea.sample.android.app.MainActivity {
-   onCreate(android.os.Bundle);
 }
 ```
-`-allowpackage`指定哪些包名下类的方法插桩。
-
-`-blockpackage`指定哪些包名下类的方法**不**插桩。
 
 当`-allowpackage`配置后，`-blockpackage`不能随意设置，`-blockpackage`包名设置必须以`-allowpackage`设置的包名开头，且必须是其子包。
 
 如上述例子，`-allowpackage`设置了‘rhea/sample/android’，那么`-blockpackage`只能设置 ‘rhea/sample/android’ 下的子包 'rhea/sample/android/test'。
 
-
 若您需要知道 App 运行过程中某些方法参数的值，那么`-allowclassmethodswithparametervalues`将助您一臂之力。如上示例，配置类名、方法名、方法签名，在您关注方法参数类型描述前加上`*`，若关注多个参数值，分别加上`*`即可。效果如下，中括号`[rhea.sample.android.app.RheaApplication]`中数据即表示参数的值。
 
 ```
  .sample.android-23670 [001] ...1 1388264.149291: tracing_mark_write: B|23670|RheaApplication:printApplicationName[rhea.sample.android.app.RheaApplication]
+
  .sample.android-23670 [001] ...1 1388264.149391: tracing_mark_write: E|23670|RheaApplication:printApplicationName[rhea.sample.android.app.RheaApplication]
 ```
-RheaTrace 提供方法粒度的过滤规则`-blockclassmethods`，您可以配置指定方法不做插桩处理，比如一些高频函数或一定不耗时方法等。
 
 ### applyMethodMappingFilePath 配置规则
 
 当 `traceWithMethodID` 值为 true，会在 app/build/outputs 目录下生成一个 `methodMapping` 文件，格式如下。
 
 ```
 1,17,rhea.sample.android.app.FirstFragment$onViewCreated$1 onClick (Landroid/view/View;)V
+
 2,17,rhea.sample.android.app.SecondFragment$onViewCreated$1 onClick (Landroid/view/View;)V
+
 3,4,rhea.sample.android.app.RheaApplication attachBaseContext (Landroid/content/Context;)V
+
 4,1,rhea.sample.android.app.FirstFragment onCreateView (Landroid/view/LayoutInflater;Landroid/view/ViewGroup;Landroid/os/Bundle;)Landroid/view/View;
+
 5,1,rhea.sample.android.app.MainActivity onCreateOptionsMenu (Landroid/view/Menu;)Z
+
 6,1,rhea.sample.android.app.RheaApplication onCreate ()V
+
 7,1,rhea.sample.android.app.FirstFragment onViewCreated (Landroid/view/View;Landroid/os/Bundle;)V
+
 8,1,rhea.sample.android.app.MainActivity onOptionsItemSelected (Landroid/view/MenuItem;)Z
+
 9,1,rhea.sample.android.app.MainActivity onWindowFocusChanged (Z)V
+
 10,17,rhea.sample.android.app.MainActivity$onCreate$1 onClick (Landroid/view/View;)V
+
 11,8,rhea.sample.android.app.MainActivity$onCreate$1 <clinit> ()V
+
 12,1,rhea.sample.android.app.SecondFragment onCreateView (Landroid/view/LayoutInflater;Landroid/view/ViewGroup;Landroid/os/Bundle;)Landroid/view/View;
+
 13,1,rhea.sample.android.app.SecondFragment onViewCreated (Landroid/view/View;Landroid/os/Bundle;)V
+
 1048574,1,android.os.Handler dispatchMessage (Landroid.os.Message;)V
 ```
-其格式为：**方法 ID, 方法 accessFlag, 类名, 方法名, 方法签名, 方法返回值**，您按照如上格式配置需要固定 ID 的方法即可。
 
+其格式为：**方法 ID, 方法 accessFlag, 类名, 方法名, 方法签名, 方法返回值**，您按照如上格式配置需要固定 ID 的方法即可。