HarmonyOS AbcKitTS Bytecode Instrumentation: 7 Practical Scenarios Explained

Project Overview

AbcKitTS is HarmonyOS's ArkTS bytecode manipulation toolchain that enables developers to instrument, analyze, and transform compiled ABC (Ark Bytecode) files. This example project showcases seven typical scenarios demonstrating the power of bytecode instrumentation: lifecycle function instrumentation, function duration statistics, privacy API monitoring, method call replacement, key attribute modification, click event instrumentation, and method parameter validation.

In performance optimization and observability, source-code-level instrumentation often suffers from high invasiveness and maintenance costs. AbcKitTS provides a post-compilation instrumentation approach, allowing developers to perform precise instruction-level operations on ArkTS bytecode without modifying business source code, achieving zero-intrusion monitoring, instrumentation, and enhancement capabilities.

Project Structure

The project organizes concerns clearly: entry module: business pages and interaction demos, including MainPage.ets and seven scene files under pages/scene/ (LifeCycle.ets, FunctionDuration.ets, PrivacyApi.ets, CallReplace.ets, KeyAttribute.ets, EventCallbackBeforeTs.ets, MethodParameter.ets). common module: reusable UI components (CardContainer, Cell) and utilities (Logger, TimeUtil). abckitTask module (core): all instrumentation logic written in TypeScript and compiled into independent plugin scripts. Each scenario has a dedicated task file: LifeCycleTask.ts, DurationTask.ts, PrivacyApiScanTask.ts, CallReplaceTask.ts, KeyAttributeModifyTask.ts, EventCbTask.ts, MethodParameterValidateTask.ts.

Instrumentation Architecture & Hvigor Plugin Integration

Instrumentation occurs at build time via a custom Hvigor plugin aspectPlugin that intercepts compiled ABC files in the transformAbc hook and invokes the instrumentation scripts:

function aspectPlugin(): HvigorPlugin {
  return {
    pluginId: 'aspectPlugin',
    apply(node: HvigorNode): void {
      hvigor.nodesEvaluated(async () => {
        node.subNodes(subNode => {
          const context = subNode.getContext(...) as OhosContext;
          context.transformAbc(async (abcPath: string, config: any) => {
            const child = spawnSync('node', [
              './abckitTask/dist/index.js', abcPath
            ]);
          });
        });
      });
    },
  };
}

After registering the plugin in hvigorfile.ts, every hvigorw assembleHap execution automatically runs the instrumentation tasks. The entry script index.ts sequentially executes all tasks:

const abcManger = new AbcManager(abcPath);
new DurationTask(abcManger).run();
new EventCbTask(abcManger).run();
new CallReplaceTask(abcManger).run();
new KeyAttributeModifyTask(abcManger).run();
new LifeCycleTask(abcManger).run();
new MethodParameterValidateTask(abcManger).run();
new PrivacyApiScanTask(abcManger).run();
abcManger.writeAbc(outPath);

This architecture ensures complete decoupling of instrumentation logic from business code: business developers write pure ArkTS, while instrumentation developers write transformation logic in a separate TypeScript project.

Scenario 1: Lifecycle Function Instrumentation

Demonstrates inserting custom code at the entry of a specified function. Using ComponentA 's aboutToAppear as example, instrumentation automatically sets a message property at function start:

// abckitTask/src/task/LifeCycleTask.ts
export class LifeCycleTask {
  run(): void {
    this.getTargetFunction();
    this.transform();
    this.manager.flush();
  }

  getTargetFunction(): void {
    const functions = this.manager.query()
      .projectModule('entry')
      .path('src/main/ets/pages/scene/LifeCycle')
      .className('ComponentA')
      .functionName('aboutToAppear')
      .getFunction();
    this.targetFunc = functions[0];
  }

  transform(): void {
    const isaKit = this.targetFunc.getIsaKit();
    const instructions: Instruction[] = [];
    const moduleName = this.targetFunc.getParentModule().getName();
    const className = this.targetFunc.getParentClass().getName();

    // Create log string instruction
    const loadStringInst = isaKit.createLdaString(
      `Module[path: ${moduleName}] - struct[name: ${className}] - aboutToAppear is executed.`
    );
    // Assign string to message property
    const stobjbynameInst = isaKit.createStObjByName(
      loadStringInst, 'message', params[params.length - 1]
    );

    instructions.push(loadStringInst, stobjbynameInst);
    this.targetFunc.insertBefore(instructions);
    this.targetFunc.apply();
  }
}

Key highlights: AbcManager.query() chainable API enables four-level precise targeting via projectModule, path, className, functionName. insertBefore inserts new instructions before the first instruction, and apply() persists modifications to bytecode.

Scenario 2: Function Duration Statistics (Around Instrumentation)

Shows a more complex pattern: around instrumentation. Inserts start-time recording at function entry and end-time calculation plus logging before every return point:

export class DurationTask {
  run(): void {
    this.getTargetFunction();
    this.doTransform();
    this.manager.flush();
  }

  doTransform(): void {
    const startTimeInst = this.doInsertBefore();
    this.doInsertAfter(startTimeInst);
    this.targetFunc?.apply();
  }

  doInsertBefore(): Instruction {
    const startTimeInsts = this.createTimeInstructions();
    this.targetFunc?.insertBefore(startTimeInsts);
    return startTimeInsts[startTimeInsts.length - 1];
  }

  doInsertAfter(startTimeInst: Instruction): void {
    const isaKit = this.targetFunc.getIsaKit();
    for (const inst of this.targetFunc.getInstructions()) {
      // Find all RETURN instructions
      const isReturn = isaKit.iGetOpcode(inst) === 
        IsaApiDynamicOpcode.ABCKIT_ISA_API_DYNAMIC_OPCODE_RETURN;
      if (isReturn) {
        const afterInsts = this.createAfterInsts(startTimeInst, isaKit);
        isaKit.iInsertBefore(inst, afterInsts);
      }
    }
  }

  createTimeInstructions(): Instruction[] {
    const isaKit = this.targetFunc.getIsaKit();
    // Date.now() call
    const tryldglobalbyname = isaKit.createTryLdGlobalByName('Date');
    const ldobjbyname = isaKit.createLdObjByName(tryldglobalbyname, 'now');
    const callthis0 = isaKit.createCallThis0(ldobjbyname, tryldglobalbyname);
    return [tryldglobalbyname, ldobjbyname, callthis0];
  }
}

Implementation traverses the function's instruction stream, identifies all RETURN opcodes, and inserts duration calculation logic before each return. This around-instrumentation pattern suits performance monitoring and call-chain tracing.

Scenario 3: Privacy API Monitoring

Demonstrates inserting monitoring code before and after sensitive API calls. Using location API as example, instrumentation automatically logs calls to geoLocationManager.getCurrentLocation:

export class PrivacyApiScanTask {
  transform(): void {
    const isaKit = this.targetFunc.getIsaKit();
    for (const inst of this.targetFunc.getInstructions()) {
      // Locate geoLocationManager.getCurrentLocation call instruction
      if (isaKit.iGetOpcode(inst) === IsaApiDynamicOpcode.ABCKIT_ISA_API_DYNAMIC_OPCODE_CALLTHIS1 &&
          this.targetFunc.iGetImportDescriptor(inst)?.getName() === 'getCurrentLocation') {

        const beforeInsts = this.createBeforeInstructions();
        const afterInsts = this.createAfterInstructions();

        isaKit.iInsertBefore(inst, beforeInsts);
        isaKit.iInsertAfter(inst, afterInsts);
      }
    }
    this.targetFunc.apply();
  }
}

Via iGetImportDescriptor, specific API call sites are identified, then pre- and post-monitoring code is inserted around the call instruction. This pattern applies broadly to privacy compliance detection and API call auditing.

Scenario 4: Method Call Replacement

Shows replacing original method calls with enhanced versions. For location API, instrumentation adds throttling logic before the original call to prevent high-frequency invocations:

export class CallReplaceTask {
  transform(): void {
    for (const inst of this.targetFunc.getInstructions()) {
      if (this.isTargetCall(inst)) {
        // Insert throttling logic
        const throttleInsts = this.createThrottleInstructions();
        // Replace original call with enhanced version
        const replaceInsts = this.createReplaceInstructions();

        isaKit.iInsertBefore(inst, throttleInsts);
        isaKit.iReplace(inst, replaceInsts);
      }
    }
  }
}

This replacement capability lets developers add caching, retry, circuit-breaking, rate-limiting, and other enhancements to existing API calls without modifying business code.

Scenario 5: Key Attribute Modification & Event Instrumentation

Two additional typical scenarios. Attribute modification instrumentation modifies component property values during specific method execution. Event instrumentation inserts tracking code into click callbacks:

// KeyAttributeModifyTask
// In changeMessage method insert: this.message = "This is New Title"

// EventCbTask
// In onClick callback insert: message = `Module[...] - onclick event is triggered.`

These patterns are highly practical for A/B testing, dynamic configuration delivery, and user behavior analysis.

Scenario 6: Method Parameter Validation

Demonstrates adding parameter validity checks at method entry. For saveUser method, instrumentation validates age parameter range at start:

export class MethodParameterValidateTask {
  transform(): void {
    // Insert age < 0 or age > 150 check logic
    // If validation fails, set error message and return early
    const checkInsts = this.createValidationInstructions();
    this.targetFunc.insertBefore(checkInsts);
    this.targetFunc.apply();
  }
}

This instrumentation pattern is especially suitable for adding defensive programming to legacy code without manually modifying each method.

Running Effects

The article includes real-device screenshots for each scenario: main page listing seven scenarios, lifecycle instrumentation log output, function duration statistics, privacy API monitoring logs, method call replacement throttling protection, key attribute modification dynamic updates, click event tracking logs, and parameter validation checks.

Summary

The AbcKitTS example project serves as a quality reference for learning HarmonyOS bytecode instrumentation. Its value spans three levels:

Entry level : Seven typical scenarios cover core instrumentation patterns — pre-instrumentation, post-instrumentation, around instrumentation, call-site replacement, attribute modification. Beginners can start with simple lifecycle instrumentation and progressively understand ABC bytecode instruction model and ISA APIs.

Advanced level : The project fully demonstrates AbcKitTS workflow — from AbcManager initialization, query chainable API usage, instruction creation and insertion, to final flush persistence. Hvigor plugin integration also provides a reference for production engineering adoption.

Engineering level : Complete decoupling of instrumentation code from business code, independent TypeScript plugin architecture, unified logging and error handling — these designs can be directly migrated to production projects.

For HarmonyOS app developers facing performance monitoring, privacy compliance, automated instrumentation needs, AbcKitTS offers a zero-intrusion source-code solution. Recommend using this project as a capability reference manual, selecting appropriate instrumentation patterns per business scenario.

Project repository: https://gitcode.com/HarmonyOS_Samples/abckit-ts

Tech stack: HarmonyOS / ArkTS / AbcKitTS / HMRouter