Mastering HarmonyOS Crash Monitoring: From Native Crashes to ArkTS Stack Traces

Background

With the official release of HarmonyOS Next, Huawei has fully shifted to a pure HarmonyOS stack, removing dependence on AOSP, using ArkTS as the primary language, and building a unified kernel and runtime with the Ark Compiler and distributed architecture. This improves performance and security but introduces new challenges for application stability monitoring.

Exception Handling Overview

The article systematically explains the full‑link solution for crash capture, context collection, and symbolization for native HarmonyOS applications. System‑level crashes are divided into two technical layers:

1) Native Layer Crashes (NativeCrash)

When C/C++ code triggers signals such as SIGSEGV, SIGABRT, SIGFPE, SIGILL, or SIGBUS, the system generates a NativeCrash event. These crashes usually stem from memory‑management errors, race conditions, or hardware faults and require core‑dump analysis and symbol mapping to locate the root cause.

2) JavaScript/ArkTS Layer Crashes (JsError)

Runtime exceptions such as ReferenceError, TypeError, SyntaxError, or AssertionError are recorded as JsError events. Developers can debug these via DevTools console logs, promise chain tracing, and try/catch blocks.

Simulating Crashes

Two UI button examples demonstrate how to trigger crashes for testing.

ItemButton({ btnName: "CPP_CRASH", fonSize: 12 })
    .width('30%')
    .onClick(() => { libentry.createCppCrash() })

The corresponding C++ crash implementation:

// Construct CPP CRASH
static napi_value CreateCppCrash(napi_env env, napi_callback_info info) {
    throw std::runtime_error("This is a CPP CRASH");
}

Clicking the button causes the app to crash, and the FaultLog in DevEco Studio shows the stack trace.

ItemButton({ btnName: "JS_CRASH", fonSize: 12 })
    .width('30%')
    .onClick(() => { throw new Error('发生了一个错误'); })

Similarly, a JavaScript crash appears in the FaultLog.

hiAppEvent Monitoring Solution

Using the hiAppEvent system, developers can register a watcher early in the app lifecycle (e.g., in

EntryAbility.ets

onCreate

) to capture all crash types.

import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
let watcher = {
  name: "MyCrashWatcher",
  appEventFilters: [/* ... */],
  onReceive: (domain, appEventGroups) => {
    hilog.info(0x0000, 'MyCrashReporter', 'Crash event received!');
    for (const eventGroup of appEventGroups) {
      for (const eventInfo of eventGroup.appEventInfos) {
        const crashReport = {
          time: eventInfo.params['time'],
          crash_type: eventInfo.params['crash_type']
          // ... other metadata
        };
        const logFilePath = eventInfo.params['external_log'] ? eventInfo.params['external_log'][0] : null;
        uploadCrashReport(crashReport, logFilePath);
      }
    }
  }
};
hiAppEvent.addWatcher(watcher);

The uploadCrashReport function should:

Send the JSON crash report to the server.

If a log file path exists (typically for native crashes), read the file and upload its contents together with the report.

Obtaining Build Artifacts for Stack Resolution

Accurate stack reconstruction requires three types of build artifacts:

ArkTS source‑map files (release mode):

{ProjectPath}/{ModuleName}/build/{product}/cache/default/default@CompileArkTS/esmodule/release/sourceMaps.map

C++ debug .so files with symbols (enable -DCMAKE_BUILD_TYPE=RelWithDebInfo in buildOption/externalNativeOptions):

{ProjectPath}/{ModuleName}/build/{product}/intermediates/libs

Obfuscation nameCache files for ArkTS:

{ProjectPath}/{ModuleName}/build/{product}/cache/default/default@CompileArkTS/esmodule/release/obfuscation

The Build ID embedded in the native .so matches the UUID shown in the crash stack, ensuring the correct debug file is used.

Stack Trace Parsing Principles

For native crashes, hstack invokes llvm‑addr2line with the debug .so to map program‑counter addresses to source files, line numbers, and function signatures, also performing C++ name demangling.

For ArkTS crashes, the sourceMaps.map file provides a key (e.g., entry|har1|1.0.0|src/main/ets/pages/w.ts) that directly indexes the mapping block. The mappings string (VLQ‑encoded) translates bytecode positions to source positions. The sources and names arrays supply file names and original identifiers.

After source‑map resolution, the nameCache.json file restores obfuscated identifiers using caches such as IdentifierCache, MemberMethodCache, and PropertyCache, ensuring the final stack trace shows meaningful variable and function names.

Summary

The complete workflow—from native signal capture to ArkTS runtime errors, through hiAppEvent monitoring, crash simulation, artifact collection, and stack‑trace reconstruction with llvm‑addr2line, source maps, and nameCache—enables developers to build high‑availability HarmonyOS applications, reduce user churn, and maintain robust stability.

References

Huawei official documentation: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiappevent-intro

Related Resources

Alibaba Cloud ARMS HarmonyOS SDK provides out‑of‑the‑box crash collection and analysis with session tracing. See the integration guide: https://help.aliyun.com/zh/arms/user-experience-monitoring/access-harmonyos-application