Migration guides

Use these migration guides to update Kanzi applications that use Kanzi Monitor.

Kanzi 4.1.0

1.41.0

Kanzi Monitor 1.41.0 is the first release of Kanzi Monitor for Kanzi 4.1. If you are migrating from Kanzi Monitor 1.40.0 (built for Kanzi 4.0.0), update your Kanzi Engine SDK to 4.1.0 Alpha 2 and review the following changes.

  • Kanzi Monitor 1.41.0 requires Kanzi 4.1.0 Alpha 2 or newer. Update your application’s KANZI_HOME, Conan profile, or other Kanzi SDK reference accordingly.

  • The example application under examples/monitor_example/ is compatible with, and uses, the application templates from Kanzi 4.1.0 Alpha 2. If you base your integration on the example, follow the Kanzi 4.1.0 Alpha 2 SDK documentation for the template structure.

  • The application CMakeLists.txt generated by Kanzi Studio 4.1.0 now ships a pre-made if(KANZI_LINK_KZMONITOR) detection and linking block. For projects created with Kanzi 4.1.0 you no longer need to add that block by hand — enable Kanzi Monitor by passing -DKANZI_LINK_KZMONITOR=ON. The manual block documented in Integrating Kanzi Monitor from source code and Integrating Kanzi Monitor as a prebuilt library is only needed for projects that predate 4.1.0 or whose generated CMakeLists.txt does not already contain it.

  • Android: Kanzi Monitor no longer ships an AAR. If your Kanzi Monitor 1.40.0 integration depended on the monitor-* AAR — whether for the bundled libkzmonitor.so or the Java API — remove that dependency. Kanzi Monitor exposes no Java API, and you build libkzmonitor.so into your APK by passing -DKANZI_LINK_KZMONITOR=ON to your kanzinative module’s CMake configuration. See Integrating Kanzi Monitor as a prebuilt library for the full integration steps.

  • Android: the trace output directory has moved from external storage (/sdcard/) to the host application’s internal files directory (Context.getFilesDir(), typically /data/user/0/<package>/files/). Kanzi Monitor resolves the path at runtime via JNI, so it adapts to whichever host app loads the plugin. Update any device-side scripts that pulled trace files from /sdcard/ — use adb shell run-as <package> ls files/ to list the new location and adb shell run-as <package> cat files/<trace>.json > <trace>.json to copy traces off the device. The internal directory does not need MANAGE_EXTERNAL_STORAGE or WRITE_EXTERNAL_STORAGE, so you can drop those permissions if you used them only for trace output.

  • If you are migrating from Kanzi Monitor 1.9.x: the runtime graphics API call logging feature (the graphicslog and overwatch.graphicslog commands, the Monitor Web UI graphics logging controls, and the set_graphics_logging and get_graphics_logging MCP server tools) is not available. Kanzi 4.1 removes the underlying engine API. The feature may return in a future Kanzi release. Remove any scripts or tooling that invoke these commands.

  • Custom trace writers now register through TraceWriterRegistry instead of SampleCollector. The public symbols SampleCollector::registerWriterTask() and SampleCollector::clearWriterTasks() have been removed. Migration recipe:

    // 1.40.0
SampleCollector::clearWriterTasks();
SampleCollector::registerWriterTask(MyWriter::writeCollectorToFile);

// 1.41.0
#include "profilinghelper_writerregistry.hpp"
TraceWriterRegistry::registerWriter(
    "mywriter",
    "Custom writer (one-line human description).",
    MyWriter::writeCollectorToFile);
TraceWriterRegistry::deactivate("chrometrace");  // optional: remove the default
TraceWriterRegistry::activate("mywriter");

    A writer registered this way can also be selected from kanzimonitor.cfg via ActiveWriters = mywriter. The selection is applied once when the Trace Service initialises and re-applied once on the first User stage of the main loop, so a writer registered by a plugin module whose initialize() runs after the Trace Service’s still gets picked up by its name. See Using the Profiling Trace service for the full lifecycle.

  • Several built-in commands no longer require the Application instance to be registered with Monitor, and the app-prefixed names are retired:

    • appquit is removed. Use quit instead — it stops the same Kanzi main loop. Update any console scripts, serial-console macros, or tooling that sent appquit.

    • appfpsinfo is renamed to fpsinfo; the reported FPS value is unchanged. The output header changed from Application Performance Info : to FPS Info :, so update any scripts that matched the old header.

    • perfinfolevel keeps its name and behavior but is now always available (it previously required the Application to be registered). Its output header changed from Application PerformanceInfo level: to PerformanceInfo level:.

    The setApplication (C++) and setNativeRuntime / setNativeApplication (Java JNI) injection API is removed in this release. Kanzi Monitor resolves the scene graph through Domain::getScreens(), so a stock Kanzi 4.1 host needs no injection — remove any setApplication / setNativeRuntime / setNativeApplication calls from your integration. The NodeRegisteringScreenEnabled configuration key and its Screen-metaclass override are likewise removed; the Startup Prefab and the host’s view Screens are now discovered automatically.

    The view-root registration hook (KanziMonitorModule::ApplicationReference::registerRoot(...) in C++ and KanziMonitorPlugin.registerNativeViewRoot(...) in Java) is removed along with the ApplicationReference class. Domain::getScreens() enumerates every host view root — including a programmatically-created view root on droidfw — so remove any registerNativeViewRoot / registerRoot calls from your integration; the tree is discovered automatically.

  • The appfps performance metric is removed. It duplicated fps — both read the same frame-time queue through the Kanzi 4.1 Domain. Update any performance watchers that referenced appfps to use fps.

Kanzi 4.0.0

1.40.0

This is the first release of Kanzi Monitor for the Kanzi version 4 generation. No migration is supported or required.

See also

Release notes

Known issues