1# 崩溃事件介绍 2<!--Kit: Performance Analysis Kit--> 3<!--Subsystem: HiviewDFX--> 4<!--Owner: @chenshi51--> 5<!--Designer: @Maplestory--> 6<!--Tester: @yufeifei--> 7<!--Adviser: @foryourself--> 8 9## 简介 10 11崩溃是指应用进程非预期退出，以下两种场景会生成崩溃事件： 12 131. Native代码未处理[崩溃信号](cppcrash-guidelines.md#系统处理的崩溃信号)时，会生成NativeCrash类型崩溃事件。 14 152. ArkTS/JS代码未处理异常时，会生成JsError类型崩溃事件。 16 17本文面向开发者介绍崩溃事件检测原理，以及各字段的含义和规格。如需了解如何使用HiAppEvent接口订阅系统崩溃事件，请参考以下文档。目前提供ArkTS和C/C++两种接口，按需选择。 18 19- [订阅崩溃事件（ArkTS）](hiappevent-watcher-crash-events-arkts.md)。 20 21- [订阅崩溃事件（C/C++）](hiappevent-watcher-crash-events-ndk.md)。 22 23## 检测原理 24 25### NativeCrash崩溃类型检测原理 26 27系统的进程崩溃检测能力主要基于POSIX信号机制，当进程崩溃后收到崩溃信号，进入系统注册信号处理流程，进行崩溃信息收集、事件生成、事件上报等操作，最终将崩溃事件发布给应用进程的崩溃事件订阅者。 28 29系统检测进程崩溃的详细流程如下： 30 311. 进程运行时崩溃后收到来自内核发送的崩溃信号，由进程在启动时注册的信号处理模块进行处理。 32 332. 进程接收到崩溃信号后，保存当前进程上下文并fork出子进程执行ProcessDump二进制抓取崩溃信息。 34 353. ProcessDump进程收集完崩溃信息后，上报给Hiview进程。Hiview进程将事件信息存储到[应用沙箱目录](../file-management/app-sandbox-directory.md)。 36 374. HiAppEvent注册的崩溃事件观察者监听到应用沙箱目录的文件变化，将事件回调给应用进程。 38 39### JsError崩溃类型检测原理 40 41在ArkTS中，JsError崩溃类型检测主要通过全局异常捕获错误，收集完错误对象的类型（如 Error、TypeError、ReferenceError） 上报给Hiview进程。Hiview进程将事件信息存储到[应用沙箱目录](../file-management/app-sandbox-directory.md)，HiAppEvent注册的崩溃事件观察者监听到应用沙箱目录的文件变化，将事件回调给应用进程，帮助开发者快速定位和修复问题。 42 43## 崩溃日志规格自定义参数设置 44 45从**API version 20**开始支持设置崩溃日志规格自定义设置。 46 47当前系统提供了通用的NativeCrash崩溃日志生成功能。然而，一些应用对NativeCrash崩溃日志打印内容有个性化的需求，因此需要设置崩溃日志配置参数。 48 49### **接口说明** 50 51| 接口名 | 描述 | 52| -------- | -------- | 53| setEventConfig(name: string, config: Record<string, ParamType>): Promise<void> | 设置崩溃日志配置参数，name需设置为崩溃事件名称常量hiappevent.event.APP_CRASH。**仅支持NativeCrash类型崩溃。** | 54 55### **参数设置说明** 56 57开发者可以使用上述HiAppEvent提供的接口，在Record<string, ParamType>中配置崩溃日志打印规格的参数。具体参数说明如下： 58 59| 参数名 | 类型 | 必填 | 说明 | 60| -------- | -------- | -------- | -------- | 61| extend_pc_lr_printing | boolean | 否 | true：64位系统打印pc和lr寄存器地址向前248字节、向后256字节范围的内存值。32位系统打印pc和lr寄存器地址向前124字节、向后128字节范围的内存值。<br/>false：64位系统打印pc和lr寄存器地址向前16字节、向后232字节范围的内存值。32位系统打印pc和lr寄存器地址向前8字节、向后116字节范围的内存值。<br/>缺省时默认为false。 | 62| log_file_cutoff_sz_bytes | number | 否 | 单位为byte，取值范围为[0-5242880]。<br/>如果设置，按设置的参数值截断崩溃日志大小。<br/>如果不设置，默认值取0表示不截断崩溃日志。 | 63| simplify_vma_printing | boolean | 否 | true：只打印崩溃日志中出现的地址所属的VMA（Virtual Memory Area，进程地址空间中的区域）映射信息，即崩溃日志中Maps，以减小日志大小。<br/>false：打印所有VMA映射信息。<br/>缺省时默认为false。 | 64 65参数配置示例如下: 66 67```text 68let configParams: Record<string, hiAppEvent.ParamType> = { 69 "extend_pc_lr_printing": true, // 使能扩展打印pc和lr寄存器附近的内存值 70 "log_file_cutoff_sz_bytes": 102400, // 截断崩溃日志到100KB 71 "simplify_vma_printing": true // 使能精简打印maps 72}; 73``` 74 75以32位系统为例，参考[订阅崩溃事件（ArkTS）开发步骤](hiappevent-watcher-crash-events-arkts.md#开发步骤)完成崩溃事件订阅和日志配置参数设置，然后通过[external_log](#params字段说明)字段获取NativeCrash类型崩溃日志内容。日志中打印如下使能的配置参数列表： 76 77```text 78... 79Build info:OpenHarmony 6.0.0.33 80Enabled app log configs: <- 使能的配置参数列表，只打印不是默认值的配置参数 81Extend pc lr printing:true <- extend_pc_lr_printing参数设置为true 82Log cut off size:102400B <- 崩溃日志大小截断到100KB 83Simplify maps printing:true <- simplify_vma_printing参数设置为true 84Timestamp:2025-05-17 19:17:07.000 85... 86``` 87 88崩溃日志详细说明见[应用通过HiAppEvent设置崩溃日志配置参数场景日志规格](cppcrash-guidelines.md#应用通过hiappevent设置崩溃日志配置参数场景日志规格)。 89 90## 事件字段说明 91 92### params字段说明 93 94崩溃事件信息中params属性的详细描述如下： 95 96| 名称 | 类型 | 说明 | 97| -------- | -------- | -------- | 98| time | number | 事件触发时间，单位为ms。 | 99| crash_type | string | 崩溃类型，支持NativeCrash（native代码异常）和JsError（js代码异常）两种类型。检测方法请参见[CppCrash（NativeCrash）检测](cppcrash-guidelines.md)和[Js Crash（JsError）检测](jscrash-guidelines.md)。 | 100| foreground | boolean | 应用是否处于前台状态。true表示应用处于前台状态；false表示应用处于后台状态。 | 101| bundle_version | string | 应用版本。 | 102| bundle_name | string | 应用名称。 | 103| pid | number | 应用的进程ID。 | 104| uid | number | 应用的用户ID。 | 105| uuid | string | 根据故障信息生成的故障特征码，用于标识特征相同的崩溃故障。 | 106| exception | object | 异常信息, 详见[exception字段说明](#exception字段说明)。包含故障简要信息，全量故障信息见external_log文件。 | 107| hilog | string[] | 日志信息，最多显示100行hilog日志。更多日志见故障日志文件。 | 108| threads | object[] | 全量线程调用栈，详见[thread字段说明](#thread字段说明)。仅在NativeCrash类型的崩溃事件提供。 | 109| external_log<sup></sup> | string[] | 故障日志文件[应用沙箱路径](../file-management/app-sandbox-directory.md)。开发者可通过路径读取故障日志文件内容。**为避免目录空间超限导致新生成的日志文件写入失败，日志文件处理完后请及时删除，超限规格请参考log_over_limit字段。** | 110| log_over_limit | boolean | 生成的与已存在的故障日志文件的大小总和是否超过5M上限。true表示超过上限，日志写入失败；false表示未超过上限。 | 111 112### exception字段说明 113 114**JsError类型exception字段说明** 115 116| 名称 | 类型 | 说明 | 117| -------- | -------- | -------- | 118| name | string | 异常类型。 | 119| message | string | 异常原因。 | 120| stack | string | 异常调用栈。 | 121 122**NativeCrash类型exception字段说明** 123 124| 名称 | 类型 | 说明 | 125| -------- | -------- | -------- | 126| message | string | 异常原因。 | 127| signal | object | 信号信息，详见[signal字段说明](#signal字段说明)。 | 128| thread_name | string | 线程名称。 | 129| tid | number | 线程ID。 | 130| frames | object[] | 线程调用栈，详见[frame字段说明](#frame字段说明)。 | 131 132### signal字段说明 133 134具体内容请参考[CppCrash（进程崩溃）检测实现原理](cppcrash-guidelines.md#实现原理)。 135 136| 名称 | 类型 | 说明 | 137| -------- | -------- | -------- | 138| signo | number | 信号值。 | 139| code | number | 信号二级分类。 | 140| address | string | 访问出错的地址。 | 141 142### thread字段说明 143 144| 名称 | 类型 | 说明 | 145| -------- | -------- | -------- | 146| thread_name | string | 线程名称。 | 147| tid | number | 线程ID。 | 148| frames | object[] | 线程调用栈，详见[frame字段说明](#frame字段说明)。 | 149 150### frame字段说明 151 152**Native frame字段说明** 153 154| 名称 | 类型 | 说明 | 155| -------- | -------- | -------- | 156| file | string | 文件名称。 | 157| symbol | string | 函数名称。symbol为空可能是由于以下两种原因：<br/>**1. 二进制文件中没有保存该函数名信息。**<br/>**2. 函数名称长度超过256字节时将被全部删除，以防止超长字符串引起未知问题。** | 158| buildId | string | 文件唯一标识。**文件可能没有buildId，请参考[CppCrash（NativeCrash）日志规格](cppcrash-guidelines.md#一般故障场景日志规格)**。 | 159| pc | string | 程序执行的指令在文件内的偏移十六进制字节数。 | 160| offset | number | 程序执行的指令在函数内偏移字节数。 | 161 162**Js frame字段说明** 163 164| 名称 | 类型 | 说明 | 165| -------- | -------- | -------- | 166| file | string | 文件名。 | 167| packageName | string | 模块的包名。 | 168| symbol | string | 函数名称。 | 169| line | number | 代码行号。 | 170| column | number | 代码列号。 | 171 172## 崩溃事件自定义参数设置 173 174当前崩溃事件上报系统通用崩溃信息，可能无法满足开发者的个性化需求，因此提供事件setEventParam方法，自定义事件上报信息。 175 176### 自定义参数设置接口 177 178| 接口名 | 描述 | 179| -------- | -------- | 180| setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> | 事件自定义参数设置方法。 | 181