在 Android 上从生产环境中获取 Perfetto Traces 和堆转储

使用平台基于触发器的 Profiling API，从 Android 应用自动捕获 heap dump 和 Perfetto Trace。

Profiling 可以捕获特定时刻的 Perfetto system trace 或 heap dump，帮助您准确了解应用在启动缓慢或卡死时正在执行什么。

Profiling 仅限 Android。它需要 Android 16（API 级别 36）或更高版本，在旧版本上不会执行任何操作。

启用 Profiling

Profiling 默认关闭，只有当 WorkManager 是应用依赖项时才会启用。KMonitor 需要它来持久化后台上传，因为 Trace 或 heap dump 通常超过 10 MB。WorkManager 不会被打进 SDK，因此不使用 Profiling 的应用不会携带该依赖。

在 build.gradle.kts 中添加 WorkManager 依赖项即可启用 Profiling。没有它，collector 不会注册，也不会捕获任何内容。

触发器

触发器是操作系统可以捕获配置文件的时机。Android 16 注册两个触发器，Android 17 及以上会额外注册三个触发器。

Android 17（API 级别 37）新增内存不足、冷启动和 CPU 使用过高触发器。KMonitor 在 Android 17 及以上设备上注册这些触发器，并使用 compileSdk 37 编译。

应用完全绘制（`app_fully_drawn`)

当应用报告第一个有意义的内容已经出现在屏幕上时触发。这不是自动的：当第一个屏幕准备好（包括异步加载的数据）后，您需要自行调用 Activity.reportFullyDrawn()。

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        viewModel.loadHome()
    }

    // Call once the first meaningful content has finished rendering.
    private fun onHomeContentReady() {
        reportFullyDrawn()
    }
}

ANR (`anr`)

当应用程序停止响应时捕获。操作系统本身会检测 ANR，因此无需在代码中添加任何内容。

操作系统对每个触发器进行速率限制，并且 KMonitor 将其上限限制为每小时每种触发器类型一个配置文件，因此重复的问题不会使时间线充满捕获。

内存不足（`oom`）

在 Android 17 及以上，应用发生内存不足异常时，系统会生成 Java 堆转储，结果以 .hprof 附件上传。应用自定义的未捕获异常处理器必须继续调用系统默认处理器，该触发器才会生效。

CPU 使用过高（`kill_excessive_cpu_usage`）

在 Android 17 及以上，系统因 CPU 使用过高终止应用时，会生成 Perfetto Trace。

冷启动（`cold_start`）

在 Android 17 及以上，系统会从冷启动早期开始生成 Perfetto Trace 和堆栈采样结果。当前 KMonitor 上传系统 Trace；堆栈采样结果在暂不支持对应附件格式前会被忽略。

采样

分析是单独采样的，与会话采样分开。速率从 0 到 100，默认为 100，因此操作系统生成的每个配置文件都会保留。保持较高的速率：操作系统已经将每个触发器的速率限制为每小时一次，因此较低的客户端速率几乎不会收集任何数据。将其设置为远高于其他采样率。

它是如何运作的

KMonitor 使用android.os.ProfilingManager，在 Android 16 中添加的基于触发器的分析 API。SDK 将支持的上述触发器以及结果回调一起注册到操作系统。操作系统决定何时运行会话，将结果写入文件，然后将其传回，然后 KMonitor 将该文件附加到profile用产生它的触发器标记的事件。

这些工件很大，因此除了正常的事件流之外，一旦设备有网络，专门的 WorkManager 工作人员就会在后台上传它们。上传后，您可以从仪表板中的会话时间线下载结果。

Profiling