Android APM Framework

高性能 Android 应用性能监控框架
对标微信 Matrix + 快手 KOOM + Google 最佳实践

---

简介

Android APM Framework 是一个全维度 Android 性能监控框架，当前代码覆盖 15 个监控维度，从内存泄漏到 ANR，从启动耗时到网络链路，从帧率卡顿到 IO 异常——一站式解决应用性能监控需求。

核心设计理念：

• 模块化架构 — 每个 APM 维度独立模块，按需集成，零耦合
• 低侵入接入 — Apm.init(application, ApmConfig(...)) + 注册所需模块，无需修改业务代码
• 高性能采集 — 令牌桶限流 + 灰度发布 + 动态配置，生产环境可用
• 对标业界 — 借鉴微信 Matrix、快手 KOOM、Google 最佳实践

特性

全方位 15 维监控

#	维度	模块	核心能力
1	内存	apm-memory	Heap/PSS 采样、Activity/Fragment/ViewModel 泄漏检测、OOM 预警、Hprof Dump & Strip、NativeHeap 监控
2	崩溃	apm-crash	Java UncaughtExceptionHandler、Native 信号解析(SIGSEGV/SIGABRT)、Tombstone 扫描
3	ANR	apm-anr	Watchdog 默认检测、可选 SIGQUIT 回调接入、traces.txt 解析、5 类原因分类、堆栈去重
4	启动	apm-launch	6 阶段冷启动追踪、热启动/温启动、Choreographer 首帧检测、瓶颈分析
5	网络	apm-network	OkHttp Interceptor + EventListener、DNS→TCP→TLS→Headers→Body 全链路耗时、聚合统计
6	FPS	apm-fps	Choreographer VSync + FrameMetrics 双引擎、掉帧/卡顿/冻结三级分级
7	慢方法	apm-slow-method	反射 Hook Looper.mLogging + ASM 字节码插桩双引擎、栈采样、热点方法统计
8	IO	apm-io	Native PLT Hook 双层架构、FD 泄漏(/proc/self/fd)、吞吐量统计、Closeable 泄漏(PhantomReference)
9	电量	apm-battery	电量下降、CPU Jiffies，以及宿主回调接入的 WakeLock/GPS/Alarm 泛洪监控
10	SQLite	apm-sqlite	慢查询检测、主线程 DB 操作、大数据量操作、QueryPlan 分析(全表扫描/临时BTree)
11	WebView	apm-webview	页面加载、JS/白屏、并发安全的资源瀑布与显式页面隔离
12	IPC	apm-ipc	Binder 调用耗时监控、主线程阈值分级、聚合统计
13	线程	apm-thread-monitor	线程数膨胀、同名泄漏、BLOCKED 死锁检测
14	GC	apm-gc-monitor	GC 频次飙升、GC 耗时占比、Heap 增长、分配频率、GC 回收率
15	渲染	apm-render	View 树数量检测、层级深度检测；过度绘制列入 Roadmap

核心能力

• 令牌桶限流 — RateLimiter 支持 ERROR/FATAL 级别跳过限流，保护上报通道
• 灰度发布 — GrayReleaseController 支持按比例开启新模块
• 动态配置 — DynamicConfigProvider 运行时调整阈值，无需发版
• 可靠出箱 — 默认 SQLite 持久化，上传成功后确认删除，进程重启自动回放
• 批量上传 — 单请求批量 + Gzip + 有界优先级队列 + 指数退避
• 关键事件落盘 — Crash 等关键事件支持同步持久化，不等待网络请求
• SDK 自监控 — 上报 emit/drop/queue/latency 健康指标，并支持自动降级
• ASM 插桩 — AGP instrumentation API + ASM 字节码级方法耗时采集
• Native Hook — CMake 构建 libapm-io.so，运行时动态解析 xhook 实现 IO 拦截，缺失时自动降级
• Hprof 裁剪 — 二进制解析 + 原始数组剥离，大幅缩小 dump 文件

架构

┌──────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│                      (Your App)                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│   │ Memory   │ │ Crash    │ │ ANR      │ │ Launch   │       │
│   └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│   │ Network  │ │ FPS      │ │ SlowMethod│ │ IO       │       │
│   └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │  Feature 层
│   │ Battery  │ │ SQLite   │ │ WebView  │ │ IPC      │       │  (15 模块)
│   └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│   │ Thread   │ │ GC       │ │ Render   │                    │
│   └──────────┘ └──────────┘ └──────────┘                    │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────────────┐  ┌──────────────┐  ┌──────────────┐       │  Core 层
│   │  apm-core   │  │  apm-model   │  │  apm-storage │       │  (4 基础模块)
│   │  分发/限流   │  │  事件模型     │  │  本地存储     │       │
│   │  灰度/日志   │  │  LineProtocol│  │ SQLite Outbox│       │
│   └─────────────┘  └──────────────┘  └──────────────┘       │
│   ┌──────────────┐                                           │
│   │  apm-uploader│  重试/批量/退避                            │
│   └──────────────┘                                           │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│   ┌──────────────────┐  ┌──────────────────┐                │  Tool 层
│   │   apm-plugin     │  │  apm-sample-app  │                │
│   │ included build + │  │   示例应用        │                │
│   │  Gradle ASM 插桩 │  │                  │                │
│   └──────────────────┘  └──────────────────┘                │
└──────────────────────────────────────────────────────────────┘

快速开始

环境要求

• Android Studio（包含 JDK 21 的当前稳定版本）
• JDK 21
• Kotlin 2.2.21
• AGP 8.13.2 / Gradle 8.13
• compileSdk 34 / minSdk 24

构建

# Debug 构建
./gradlew assembleDebug

# 运行单元测试
./gradlew testDebugUnitTest

# 构建 + 测试
./gradlew assembleDebug testDebugUnitTest

# Lint、Release 和发布消费验证
./gradlew lintDebug assembleRelease publishToMavenLocal
./gradlew -p smoke-tests/maven-consumer clean assembleDebug

当前仓库通过 pluginManagement { includeBuild("apm-plugin") } 解析本地 slow-method 插件。 插件已迁移到 AGP instrumentation API，不再依赖 legacy Transform 兼容开关。

集成

1. 添加模块依赖

发布到 Maven 仓库后，功能模块会传递暴露 apm-core：

dependencies {
    implementation("com.apm:apm-memory:0.1.0")
    implementation("com.apm:apm-network:0.1.0")
}

仓库内开发也可以继续使用 project 依赖：

// settings.gradle.kts
include(":apm-core")
include(":apm-model")
include(":apm-storage")
include(":apm-uploader")
include(":apm-memory")    // 按需添加
include(":apm-crash")
include(":apm-anr")
include(":apm-launch")
// ... 其他所需模块

2. 初始化

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Apm.init(this, ApmConfig())            // 初始化框架

        Apm.register(MemoryModule())            // 内存监控
        Apm.register(CrashModule())             // 崩溃监控
        Apm.register(AnrModule())               // ANR 监控
        Apm.register(LaunchModule())            // 启动监控
        Apm.register(NetworkModule())           // 网络监控
        Apm.register(FpsModule())               // FPS 监控
        Apm.register(SlowMethodModule())        // 慢方法检测
        Apm.register(IoModule())                // IO 监控
        // ... 按需注册其他模块

    }
}

3. 自定义配置

// 单模块自定义配置
val memoryConfig = MemoryConfig(
    sampleIntervalMs = 2000,
    leakDetectEnabled = true,
    oomMonitorEnabled = true
)
Apm.register(MemoryModule(memoryConfig))

// 全局限流配置
val apmConfig = ApmConfig(
    endpoint = "https://apm.example.com/v1/events",
    rateLimitEventsPerWindow = 10,
    rateLimitWindowMs = 60_000L,
    enableRetry = true,
    maxRetries = 3
)
Apm.init(this, apmConfig)

4. 自定义上报

// 实现 ApmUploader 接口
class MyUploader : ApmUploader {
    override fun upload(event: ApmEvent): Boolean {
        // 上报至你的 APM 后台
        return myApiClient.send(event)
    }
}

// 通过 ApmConfig 注入
Apm.init(
    this,
    ApmConfig(
        uploader = MyUploader(),
        enableRetry = false
    )
)

5. 网络监控接入

// OkHttp 客户端添加监控
val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(NetworkModule.interceptor)
    .eventListenerFactory(NetworkModule.eventListenerFactory)
    .build()

模块一览

模块	包名	说明
apm-model	事件模型	ApmEvent + Line Protocol 序列化
apm-core	核心框架	初始化/注册/分发/限流(令牌桶)/灰度/多进程/日志
apm-storage	本地存储	SQLite 持久化出箱与确认删除 + File RingBuffer 兼容路径
apm-uploader	上传通道	HTTP 单请求批量/Gzip + Logcat + 有界重试队列
apm-memory	内存监控	水位采样 + 泄漏检测 + OOM 预警 + Hprof Dump + fork dump + 引用链分析
apm-crash	崩溃监控	Java + Native 信号处理器 + Tombstone
apm-anr	ANR 监控	Watchdog + 可选 SIGQUIT 回调 + traces.txt 解析
apm-launch	启动监控	冷/热/温启动 + 6 阶段追踪
apm-network	网络监控	OkHttp 全链路 (DNS→TCP→TLS→Body)
apm-fps	FPS 监控	Choreographer VSync + FrameMetrics
apm-slow-method	慢方法	Looper Hook + ASM 字节码插桩
apm-io	IO 监控	Native PLT Hook + FD 泄漏 + Closeable 泄漏 + 零拷贝检测
apm-battery	电量监控	电量/CPU + WakeLock/GPS/Alarm 宿主回调 API
apm-sqlite	SQLite 监控	慢查询 + QueryPlan 分析
apm-webview	WebView 监控	页面加载 + JS 执行 + 白屏 + JS Bridge + 资源瀑布图
apm-ipc	IPC 监控	Binder 调用耗时
apm-thread-monitor	线程监控	膨胀/泄漏/死锁
apm-gc-monitor	GC 监控	频次/耗时/Heap/分配率/回收率
apm-render	渲染监控	View 树深度/数量
apm-plugin	Gradle 插件	included build，基于 AGP instrumentation API 提供 ASM 字节码插桩
apm-sample-app	示例应用	全模块集成 Demo

与业界方案对比

能力	Android APM	微信 Matrix	快手 KOOM
内存泄漏 (Activity/Fragment/ViewModel)	✅	✅	✅
OOM 预警 + Hprof Dump	✅	✅	✅
Hprof 裁剪	✅	✅	✅
引用链分析 (Hprof 解析 + BFS)	✅	✅	✅
fork 子进程 Dump (显式开启)	✅	❌	✅
NativeHeap 监控	✅	❌	✅
Java 崩溃	✅	✅	❌
Native 崩溃信号处理器 + Tombstone	✅	✅	❌
ANR 检测 (Watchdog + 可选 SIGQUIT)	✅	✅	❌
ANR 原因分类	✅ (5 类)	❌	❌
冷启动 6 阶段	✅	✅	❌
热启动/温启动	✅	✅	❌
网络全链路 (DNS→Body)	✅	❌	❌
FPS 双引擎	✅	✅	❌
慢方法 Hook + ASM	✅	✅	❌
IO Native PLT Hook	✅	✅	❌
FD 泄漏检测	✅	✅	❌
Closeable 泄漏	✅	❌	❌
零拷贝检测	✅	❌	❌
SQLite QueryPlan 分析	✅	❌	❌
Binder IPC 监控	✅	❌	❌
线程死锁检测	✅	❌	❌
GC 监控 (5 维度)	✅	❌	❌
View 树分析	✅	❌	❌
WakeLock + CPU Jiffies	✅	❌	❌
WebView 性能 + JS Bridge + 资源瀑布图	✅	❌	❌
HTTP 上传通道 + Gzip 压缩	✅	❌	❌
多进程支持 (ContentProvider 自动初始化)	✅	❌	❌
令牌桶限流 + 灰度发布	✅	❌	❌
Gradle ASM 字节码插桩	✅	❌	❌
模块数量	15 监控 + 4 基础 + 2 扩展	6 插件	3 模块

项目结构

Android-APM/
├── apm-core/                  # 核心框架 (分发/限流/灰度)
│   └── throttle/              # 令牌桶限流 + 动态配置 + 灰度发布
├── apm-model/                 # 统一事件模型 + Line Protocol
├── apm-storage/               # 本地存储 (SQLite 出箱 + File 兼容路径)
├── apm-uploader/              # 上传通道 (重试/批量/退避)
├── apm-memory/                # 内存监控
│   ├── leak/                  # Activity/Fragment/ViewModel 泄漏
│   ├── oom/                   # OOM 预警 + Hprof Dump/Strip
│   └── nativeheap/            # NativeHeap 监控
├── apm-crash/                 # 崩溃监控 (Java + Native)
├── apm-anr/                   # ANR 监控 (Watchdog + 可选 SIGQUIT)
├── apm-launch/                # 启动监控 (冷/热/温)
├── apm-network/               # 网络监控 (OkHttp)
├── apm-fps/                   # FPS 监控 (VSync + FrameMetrics)
├── apm-slow-method/           # 慢方法 (Hook + ASM)
├── apm-io/                    # IO 监控 (PLT Hook + FD)
├── apm-battery/               # 电量监控 (WakeLock + CPU)
├── apm-sqlite/                # SQLite 监控 (慢查询 + QueryPlan)
├── apm-webview/               # WebView 监控
├── apm-ipc/                   # IPC 监控 (Binder)
├── apm-thread-monitor/        # 线程监控
├── apm-gc-monitor/            # GC 监控
├── apm-render/                # 渲染监控 (View 树)
├── apm-plugin/                # Gradle 插件 (ASM)
├── apm-sample-app/            # 示例应用
├── docs/                      # 文档
│   ├── Android_APM_项目文档.md # 完整项目文档
│   └── architecture/          # 架构图 (18 个模块详细文档)
├── CLAUDE.md                  # 编码规范
├── build.gradle.kts           # 根构建文件
└── settings.gradle.kts        # 模块配置

文档

文档	说明
项目文档	完整项目文档：功能对比矩阵、模块设计、测试覆盖
整体架构	系统全景架构、模块依赖、事件流程、线程模型
模块架构	18 个文件的逐模块架构文档（类图/流程图/检测维度）

开源参考

本项目借鉴了以下优秀开源项目的设计思路：

• 微信 Matrix — APM 插件化架构、IO/Hook 方案
• 快手 KOOM — 内存监控、Hprof 裁剪、NativeHeap
• bytedance/bhook — PLT Hook 实现
• square/leakcanary — 内存泄漏检测
• android/perfetto — 系统级性能分析

贡献

欢迎提交 Issue 和 Pull Request。

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/your-feature)
3. 提交更改 (git commit -m 'Feat: your feature')
4. 推送分支 (git push origin feature/your-feature)
5. 创建 Pull Request

License

Copyright 2024 Android APM Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.