Update documentation

Signed-off-by: xueqiushi <[email protected]>
KwaiAppTeam · May 16, 2022 · 5d7b0cf · 5d7b0cf
1 parent b86c916
commit 5d7b0cf
Show file tree

Hide file tree

Showing 4 changed files with 182 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -27,6 +27,38 @@ The app freezes for a long time during the dump. For details, please refer to [h
 - The `koom-thread-leak` module is used for Thread leak monitoring: it hooks the life cycle 
   function of the thread, and periodically reports the leaked thread information. For details, please refer to [here](./koom-thread-leak/README.md)
 
+## STL Support
+All Native modules support two access modes, c++_shared and c++_static. For details, please 
+refer to [cpp-support](https://developer.android.com/ndk/guides/cpp-support).
+- Add dependency to the project build.gradle (take koom-fast-dump as an example)：
+```groovy
+dependencies {
+  // In shared mode, multiple modules share the same libc++_shared.so (STL), and the package 
+  // size is small, but when multiple modules depend on different STL versions, the final 
+  // compilation will conflict.
+  implementation "com.kuaishou.koom:koom-fast-dump:${latest_version}"
+  // Or in static mode, each module has its own STL, the package size is large, and there are no 
+  // compilation and runtime problems.
+  implementation "com.kuaishou.koom:koom-fast-dump-static:${latest_version}"
+}
+```
+- Introduce a way to resolve the conflict of shared mode, add `pickFirst` in the project root 
+  directory build.gradle：
+```groovy
+packagingOptions {
+  // Select the first libc++_shared.so when packaging apk, it may encounter unpredictable bugs 
+  // at runtime, use it with caution!
+  pickFirst 'lib/*/libc++_shared.so'
+}
+```
+
+## minSdk
+- The minSdk of all modules is 18. If the minSdk of your app is lower than that, it needs to be 
+  compatible with overrideLibrary in the manifest.
+```xml
+  <uses-sdk tools:overrideLibrary="com.kwai.koom.fastdump, com.kwai.android.base, com.kwai.koom.base" />
+```
+
 ## License
 KOOM is under the Apache license 2.0. For details check out the [LICENSE](./LICENSE).
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -9,11 +9,37 @@ KOOM(Kwai OOM, Kill OOM)是快手性能优化团队在处理移动端OOM问题
 ## KOOM 功能
 ### Java Heap 泄漏监控
 - `koom-java-leak` 模块用于 Java Heap 泄漏监控：它利用 Copy-on-write 机制 fork 子进程 dump Java Heap，解决了 
-  dump 过程中 app 长时间冻结的问题，详情参考[这里](./koom-java-leak/README.zh-CN.md)
+  dump 过程中 app 长时间冻结的问题，详情参考 [这里](./koom-java-leak/README.zh-CN.md)
 ### Native Heap 泄漏监控
-- `koom-native-leak` 模块用于 Native Heap 泄漏监控：它利用 [Tracing garbage collection](https://en.wikipedia.org/wiki/Tracing_garbage_collection) 机制分析整个 Native Heap，直接输出泄漏内存信息「大小、分配堆栈等』；极大的降低了业务同学分析、解决内存泄漏的成本。详情可以参考[这里](./koom-native-leak/README.zh-CN.md)
+- `koom-native-leak` 模块用于 Native Heap 泄漏监控：它利用 [Tracing garbage collection](https://en.wikipedia.org/wiki/Tracing_garbage_collection) 
+机制分析整个 Native Heap，直接输出泄漏内存信息「大小、分配堆栈等』；极大的降低了业务同学分析、解决内存泄漏的成本。详情可以参考 [这里](./koom-native-leak/README.zh-CN.md)
 ### Thread 泄漏监控
-- `koom-thread-leak` 模块用于 Thread 泄漏监控：它会 hook 线程的生命周期函数，周期性的上报泄漏线程信息。详情参考[这里](./koom-thread-leak/README.zh-CN.md)
+- `koom-thread-leak` 模块用于 Thread 泄漏监控：它会 hook 线程的生命周期函数，周期性的上报泄漏线程信息。详情参考 [这里](./koom-thread-leak/README.zh-CN.md)
+
+## STL 支持
+所有Native模块均支持c++_shared和c++_static两种接入模式，详情参考 [cpp-support](https://developer.android.com/ndk/guides/cpp-support)
+- 项目 build.gradle 中增加依赖(以koom-fast-dump为例)：
+```groovy
+dependencies {
+  // shared模式，多个模块共享同一个libc++_shared.so，包体较小，但当多个模块依赖的STL版本不同时，最终编译会发生冲突。
+  implementation "com.kuaishou.koom:koom-fast-dump:${latest_version}"
+  // or static模式，包体较大，无编译和运行时问题。
+  implementation "com.kuaishou.koom:koom-fast-dump-static:${latest_version}"
+}
+```
+- 介绍一种解决shared模式冲突的办法，项目根目录 build.gradle 中增加pickFirst：
+```groovy
+packagingOptions {
+  // apk打包时选择第一个libc++_shared.so，运行时可能遇到不可预知的bug，慎用！
+  pickFirst 'lib/*/libc++_shared.so'
+}
+```
+
+## minSdk
+- 所有模块编译时的minSdk为18，如果接入方的minSdk低于此值，需要在manifest中通过overrideLibrary兼容：
+```xml
+  <uses-sdk tools:overrideLibrary="com.kwai.koom.fastdump, com.kwai.android.base, com.kwai.koom.base" />
+```
 
 ## License
 
@@ -40,5 +66,5 @@ KOOM 以 Apache-2.0 证书开源，详情参见 [LICENSE](./LICENSE)。
 [lbtrace(王连宝)](https://github.com/lbtrace) <br>
 [shenvsv(沈冠初)](https://github.com/shenvsv) <br>
 
-**微信讨论群**
+**微信讨论群** <br>
 <img src=./doc/images/wechat.jpg/>。
diff --git a/koom-fast-dump/README.md b/koom-fast-dump/README.md
@@ -0,0 +1,65 @@
+中文版本请参看[这里](README.zh-CN.md)
+
+# Fast Dump Introduction
+
+Java memory memory image dump module：
+
+- Image dump adopts the strategy of `current process virtual machine supend -> fork child
+    process -> current process virtual machine resume ->c hild process dump memory image`, and the 
+  time-consuming (median about 20s) of collecting images is transferred to child process, the 
+  freezing time of the current process is reduced to less than 20ms (does not affect user operations).
+
+- Adapt to LeakCanary custom dumper, which can replace LeakCanary's image acquisition module with fast dump.
+
+# Fast Dump Compatibility
+
+- Android L and above（API level >= 21）
+
+- Support armeabi-v7a arm64-v8a x86 x86-64
+
+
+# Fast Dump Setup
+
+## Dependencies
+
+- Add mavenCentral to the repositories of the project root directory build.gradle
+```groovy
+repositories {
+    mavenCentral()
+}
+```
+
+- Add dependency in project app/build.gradle
+```groovy
+dependencies {
+    implementation "com.kuaishou.koom:koom-fast-dump:${latest_version}"
+}
+```
+
+## Steps
+
+- Take the integration of fast dump into LeakCanary as an example：
+
+```kotlin
+// Configuration initialization
+DefaultInitTask.init(applicationContext as Application)
+LeakCanary.config = LeakCanary.config.copy(
+  heapDumper = HeapDumper {
+    // The core code is this line. Note that this method will wait for the child process to 
+    // return the dump result, do not call it on the UI thread!
+    ForkJvmHeapDumper.getInstance().dump(it.absolutePath)
+  })
+```
+
+
+- Key Log
+
+> 16743 16766 I OOMMonitor_ForkJvmHeapDumper: dump xxx.hprof. <br>
+> 16743 16766 I OOMMonitor_ForkJvmHeapDumper: before suspend and fork. <br>
+> // The pid changes from 16743 to 16807, and the child process starts to dump <br>
+> 16807 16807 I mple.leakcanar: hprof: heap dump "xxx.hprof" starting... <br>
+> // The child process dump finished, it takes 6.4s <br>
+> 16807 16807 I mple.leakcanar: hprof: heap dump completed (24MB) in 6.411s objects 330914 objects with stack traces 0 <br>
+> 16807 16807 I JNIBridge: process 16807 will exit! <br>
+> // The main process is notified by the completion of the child process dump <br>
+> 16743 16766 I OOMMonitor_ForkJvmHeapDumper: dump true, notify from pid 16807 <br>
diff --git a/koom-fast-dump/README.zh-CN.md b/koom-fast-dump/README.zh-CN.md
@@ -0,0 +1,55 @@
+# Fast Dump 介绍
+
+Java 内存镜像采集模块：
+
+- 镜像采集采用`当前进程虚拟机supend -> fork子进程 -> 当前进程虚拟机resume -> 子进程dump内存镜像`的策略，将采集镜像的耗时(中位数约20s)转移到
+  子进程，当前进程冻结的时间缩减至20ms以内(不影响用户操作)。
+
+- 适配LeakCanary custom dumper，可将LeakCanary的镜像采集模块替换为fast dump。
+
+# Fast Dump 适用范围
+
+- Android L 及以上（API level >= 21）
+
+- 支持 armeabi-v7a arm64-v8a x86 x86-64
+
+# Fast Dump 接入
+
+## 依赖配置
+- 项目根目录 build.gradle 中增加 mavenCentral
+```groovy
+repositories {
+    mavenCentral()
+}
+```
+- 项目 app/build.gradle 中增加依赖
+```groovy
+dependencies {
+  implementation "com.kuaishou.koom:koom-fast-dump:${latest_version}"
+}
+```
+
+## 使用
+
+- 以接入LeakCanary为例：
+
+```kotlin
+// 初始化配置
+DefaultInitTask.init(applicationContext as Application)
+LeakCanary.config = LeakCanary.config.copy(
+  heapDumper = HeapDumper {
+    // 核心代码就这一行，注意此方法会等待子进程返回采集结果，不要在UI线程调用！
+    ForkJvmHeapDumper.getInstance().dump(it.absolutePath)
+  })
+```
+## 关键日志
+
+> 16743 16766 I OOMMonitor_ForkJvmHeapDumper: dump xxx.hprof. <br>
+> 16743 16766 I OOMMonitor_ForkJvmHeapDumper: before suspend and fork. <br>
+> // pid从16743变为16807，子进程开始采集 <br>
+> 16807 16807 I mple.leakcanar: hprof: heap dump "xxx.hprof" starting... <br>
+> // 子进程采集完毕，耗时6.4s <br>
+> 16807 16807 I mple.leakcanar: hprof: heap dump completed (24MB) in 6.411s objects 330914 objects with stack traces 0 <br>
+> 16807 16807 I JNIBridge: process 16807 will exit! <br>
+> // 主进程监听到子进程采集完毕 <br>
+> 16743 16766 I OOMMonitor_ForkJvmHeapDumper: dump true, notify from pid 16807 <br>