Migration guides¶

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

Migrating from Kanzi Monitor 1.41.0 to 1.41.1¶

Kanzi Monitor 1.41.1 is a maintenance release on the same Kanzi 4.1 generation as 1.41.0, so no Kanzi engine migration is involved, and no configuration key, console command, or Overwatch JSON field changed. Two changes can need attention: one in the C++ API, for an integration that calls the plugin directly, and one in the chrometrace trace file format, for a custom tool that parses trace output.

Performance watcher comparison enum. The WatcherComparison enumerators are renamed: Below → BelowThreshold and Above → AboveThreshold. X11 headers, which the Kanzi engine pulls in on linux_x11, #define Below and Above as integer constants and textually clobbered the old names. This affects only C++ code that uses the enum directly — a call to PerformanceService::addWatcher(), or a read of PerformanceWatcher::comparison — so update those call sites to the new enumerator names. Nothing else changes: the watcher console command, the Overwatch JSON, the Monitor Web UI, and the MCP add_watcher tool all still use the "below" / "above" strings, so scripts, kanzimonitor.cfg files, and existing watcher definitions need no changes (KZMON-504).
Trace timestamps. The chrometrace writer now emits session-relative timestamps — the first event starts at 0 — instead of the platform’s absolute engine-clock values, and emits ts and dur as fractional microseconds rather than integers. The Perfetto trace viewer and the bundled tools need no changes. Update a custom tool that reads Kanzi Monitor trace files if it relies on ts being an absolute (since-boot or since-epoch) value, or assumes integer ts / dur. The perfetto and perfetto-producer writers are unchanged; perfetto-producer keeps absolute timestamps by design, so its events stay aligned with the rest of the system timeline (KZMON-505, KZMON-506).

Migrating from Kanzi Monitor 1.40.0 to 1.41.1¶

Migrating from 1.40.0 is a superset of the 1.41.0 → 1.41.1 path: apply the steps below, then all of the “Migrating from Kanzi Monitor 1.41.0 to 1.41.1” steps above.

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.1¶

Migrating from 1.9.x is a superset of the 1.40.0 → 1.41.1 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.1” steps above — which in turn end with the 1.41.0 → 1.41.1 steps. (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.1¶

Apply every step in “Migrating from Kanzi Monitor 1.40.0 to 1.41.1” 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).