Advanced Options

This section covers optional configuration, the individual Gradle tasks the plugin registers, and known viewer restrictions.

Configuration

Perfetto Format

Use the Perfetto format instead of the default Chrome DevTools format:

profiling {
    format = "perfetto"
}

RTT Address

Pin the RTT address directly to skip the resolveRttAddress task:

profiling {
    rttAddress = "0x200A0000"
}

ELF File

Override the ELF file path used by resolveRttAddress:

import com.microej.gradle.ResolveRttAddressTask

tasks.named<ResolveRttAddressTask>("resolveRttAddress") {
    elfFile = layout.buildDirectory.file("custom/path/application.out")
}

Existing Traces

Convert already-captured .SVDat files without a live capture: drop the files into build/profiling/input/ and run:

./gradlew convertTrace

Note

build/profiling/input/ is created by captureTraceOnDevice. On a project where no capture has run yet, create the directory before dropping the files in, otherwise convertTrace fails because its input directory is missing.

The converted JSON is written to build/profiling/output/ with the same base name and a format suffix (e.g. traces.SVDat → traces-devtools.json). Files whose output already exists are skipped.

Lookup Table Generation

Skip the lookup table generation described in Object Names (e.g. for projects without MWT):

./gradlew recordTraceOnDevice -x generateLookupTable

Reference

Object Names

Events that reference objects, such as widgets and animations, identify them with two numbers: a TypeID, which tells you the kind of object (its class), and an ObjectID, which identifies the individual instance. The ObjectID is what lets you tell apart two objects of the same type: for example, two Button widgets share the same TypeID but each has its own ObjectID. By default both appear as raw numbers, e.g. MWT_Render TypeID=5 ObjectID=3.

If your application was built with the MicroEJ SOAR optimizer, the resulting .optimizermap files let the profiler resolve names automatically: the generateLookupTable task picks them up and maps each TypeID to the widget’s or animation’s class name. You do not need to do anything extra: run the capture as usual and objects show up by name, with the ObjectID still distinguishing each instance:

  • MWT_Render MyWidget (ObjectID=3): in flame graphs (Tasks and Threads, Traces).

  • FadeAnimation (ObjectID=2; fps = 30Hz): in Animations slots.

If no .optimizermap is available (or you want to override the generated names), provide your own SYSVIEW_NamedType_lookup_table.txt file that maps TypeID values to names. It follows the standard SYSVIEW_*.txt format:

NamedType TypeID 5="MyWidget"
NamedType TypeID 3="FadeAnimation"

The file must keep this exact name to be recognized as a lookup table. Declare it on the convertTrace task, and keep it outside build/profiling/input/ so that generateLookupTable does not overwrite it:

import com.microej.gradle.ToCatapultTask

tasks.named<ToCatapultTask>("convertTrace") {
    descriptions.from(layout.projectDirectory.file("profiling/SYSVIEW_NamedType_lookup_table.txt"))
}

The mappings of all lookup tables are merged. The file declared this way is read after the generated table, so its entries take precedence for the same TypeID.

Tasks Reference

Applying the plugin registers the following tasks.

MicroEJ tasks

Group microej, the only ones listed by ./gradlew tasks.

  • recordTraceOnDevice: the public entry point; orchestrates the full workflow below.

Other tasks

Hidden from ./gradlew tasks, but can be invoked directly.

  • captureTraceOnDevice: captures a live SystemView trace via J-Link RTT into build/profiling/input/.

  • convertTrace: converts every .SVDat in build/profiling/input/ to Catapult JSON in build/profiling/output/.

  • extractSysviewDescriptions: extracts SYSVIEW_*.txt description files from the MicroEJ library JARs on the classpath.

  • generateLookupTable: builds SYSVIEW_NamedType_lookup_table.txt from .optimizermap files found across the project (see Object Names).

  • resolveRttAddress: extracts the _SEGGER_RTT symbol address from the application ELF file.

Restrictions

The Chromium DevTools implementation has diverged from the official Catapult format specification. Compatibility with future browser versions is not guaranteed.