Migration guides

Use these guides to update a project from an earlier version of Kanzi Monitor to Kanzi Monitor 1.41.0. Follow the section for the version you are coming from.

Migrating from Kanzi Monitor 1.40.0 to 1.41.0

Kanzi Monitor 1.40.x is built for the Kanzi 4.0 generation; 1.41.x is built for the Kanzi 4.1 generation. A given 1.41.x release is compatible with the Kanzi 4.1.y releases available at the time; the release notes list the supported Kanzi versions and call out any exceptions.

  • Engine SDK. Kanzi Monitor 1.41.x requires a Kanzi 4.1 release. Updating the Kanzi Engine SDK from the 4.0 to the 4.1 generation — and any application changes the engine update itself requires — is covered by the Kanzi SDK migration guide (4.0 → 4.1); this guide covers only the Kanzi Monitor-specific steps.

  • Build integration. The application CMakeLists.txt generated by Kanzi Studio 4.1.0 ships a ready-made if(KANZI_LINK_KZMONITOR) detection and linking block; 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 packaging. Kanzi Monitor no longer ships an AAR. If your integration depended on the monitor-* AAR — for the bundled libkzmonitor.so or the Java API — remove that dependency. Kanzi Monitor exposes no Java API; build libkzmonitor.so into your APK by passing -DKANZI_LINK_KZMONITOR=ON to your kanzinative module. See Integrating Kanzi Monitor as a prebuilt library.

  • Scene-graph resolution. Remove any setApplication (C++) or setNativeRuntime / setNativeApplication (Java JNI) injection calls, the NodeRegisteringScreenEnabled configuration key, and the registerRoot / registerNativeViewRoot view-root hook (the ApplicationReference class is removed). Kanzi Monitor discovers the scene graph through Domain::getScreens() — a stock Kanzi 4.1 host, including droidfw’s multiple views, needs no injection or registration.

  • Commands. appquit is removed — use quit (it stops the same main loop). appfpsinfo is renamed to fpsinfo (same value; output header changed from Application Performance Info : to FPS Info :). perfinfolevel keeps its name but is now always available (header changed from Application PerformanceInfo level: to PerformanceInfo level:). The appfps metric is removed — use fps. Update any scripts and performance watchers that referenced the old names or headers.

  • Custom trace writers. The public SampleCollector::registerWriterTask() / SampleCollector::clearWriterTasks() symbols are removed. Register writers through TraceWriterRegistry and select them by name:

    // 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 during TraceService::initialize(), so it covers only writers already registered at that point; a writer registered by a plugin module whose initialize() runs after the Trace Service’s must activate itself via TraceWriterRegistry::activate() or at runtime via overwatch.activatewriter. See Using the Profiling Trace service.

  • Android trace output location. Trace files now go to the host application’s internal files directory (Context.getFilesDir(), typically /data/user/0/<package>/files/, resolved at runtime via JNI) instead of /sdcard/. Drop the MANAGE_EXTERNAL_STORAGE / WRITE_EXTERNAL_STORAGE permissions if you used them only for trace output, and update device-side scripts — use adb shell run-as <package> ls files/ and adb shell run-as <package> cat files/<trace>.json > <trace>.json.

  • Configuration key. The frame-duration trigger key is now spelled WritingOnFrameDurationThreshold; the 1.40.0 misspelling WritingOnFrameDurationTreshold still works as a deprecated alias, but switch to the correct spelling.

  • Graphics API call logging. The graphicslog / overwatch.graphicslog commands and the set_graphics_logging / get_graphics_logging MCP tools carried into the 4.0 line were non-functional (Kanzi 4.x dropped the underlying engine API) and are now removed. Drop any scripts that invoked them.

Migrating from Kanzi Monitor 1.9.x to 1.41.0

Migrating from 1.9.x is a superset of the 1.40.0 → 1.41.0 migration: apply the 1.9.x → 1.40.0 changes below, then all of the “Migrating from Kanzi Monitor 1.40.0 to 1.41.0” steps above. (1.9.x targets Kanzi 3.9; 1.40.x targets Kanzi 4.0; 1.41.x targets Kanzi 4.1.)

1.9.x to 1.40.0

Kanzi Monitor 1.40.0 was essentially 1.9.x ported to the Kanzi 4.0 SDK, API, and build system, keeping the same feature set except where the Kanzi 3.9 → 4.0 engine forced a difference. The bulk of this step is therefore the Kanzi engine port — covered by the Kanzi SDK migration guide (3.9 → 4.0), not here — and Kanzi Monitor’s own surface (plugin load order, kanzimonitor.cfg keys, command names) is unchanged. The Kanzi Monitor-specific touches are:

  • Build files adopt the |k| 4.0 application templates. Regenerate or adapt your application build files to the 4.0 templates. On Android the native libraries build through an NDK module (kanzinative) and the current Gradle setup — build libkzmonitor.so (and any custom Monitor plugin) through that path.

  • Enable graphics statistics. Rendering and performance stats read as zero on Kanzi 4.0 unless the graphics-statistics layer is enabled — set graphicsStatisticsEnabled = true in your application configuration so Kanzi Monitor can report draw and triangle counts. See the Kanzi application-configuration reference.

  • Graphics information is backend-agnostic. graphicsinfo and the Web UI Graphics tab report Kanzi 4.0 backend-agnostic values rather than GL-specific labels; update any tooling that parsed the old GL-specific output.

1.40.0 to 1.41.0

Apply every step in “Migrating from Kanzi Monitor 1.40.0 to 1.41.0” above. The items most likely to affect a 1.9.x integration: the Application-injection API (setApplication / the JNI handshakes / registerRoot / ApplicationReference) is removed in favor of Domain::getScreens(); the app-prefixed commands are renamed (appfpsinfo → fpsinfo, appquit → quit, appfps → fps); custom trace writers move from SampleCollector to TraceWriterRegistry / ActiveWriters; and the graphics API call logging that worked on 1.9.x is not available (Kanzi 4.x dropped the engine API).

See also

Release notes

Known issues