Migration guides¶

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

Migrating from Kanzi Monitor 1.41.1 to 1.41.2¶

Kanzi Monitor 1.41.2 is a maintenance release on the same Kanzi 4.1 generation as 1.41.1, so no Kanzi engine migration is involved, and no configuration key or console command changed. Three changes can need attention: one in the C++ API, for an integration that reads Kanzi Monitor’s log buffer directly; one in node path resolution, for a script or tool that addresses nodes by path; and one in the Overwatch JSON, for anything that reads node property listings.

Log buffer access. KanziMonitorLogger::getLog(), which returned a reference to the log container, is removed. It is replaced by:

Before	Now
`logger->getLog()` and iterate	`logger->withLog([](const kanzi::list<LogEntry>& log) { ... })`
`logger->getLog().size()`	`logger->getEntryCount()`
`setMaxEntries()` then pop the excess yourself	`setMaxEntries()` — it trims to the new cap itself

This affects only C++ code that reads the buffer directly; the loginfo and overwatch.logs commands, the Web UI Logs tab, and the MCP get_logs tool are unchanged.

Kanzi Monitor ships its include/ directory in every package, so kanzimonitor_logger.hpp is public surface and this is a breaking change in a patch release. It is made deliberately: the buffer is written from several threads — the main thread, the remote console reader thread on every accept, and the local console reader thread — and was previously mutated with no lock at all. It is now guarded by a mutex, and an accessor that hands out a reference cannot be made safe by that mutex, because the reference outlives the lock. Keeping getLog() would have kept the defect reachable through the public API. withLog() runs your visitor while the lock is held, so keep it short, do not store the reference, and do not call back into the logger from inside it (KZMON-629).

Node paths. A path that resolves to no node now returns Node not found. Previously any single-segment path — / or /anything — resolved to the first view root, so overwatch.props and overwatch.setprop answered for that root when given a path that pointed nowhere, and a caller could not tell a deliberate root query from a malformed one. Address nodes by the path overwatch.nodes reports: it equals the engine’s own Node.Path, and every reported path now resolves. Update a script that relied on the fallback, or that addresses a node by a name the node no longer has — for example after setting Node.Name, which changes the node’s path. The unqualified /<rootName>/child form still works. On a host with more than one view tree this is a fix rather than a restriction: previously no reported path resolved at all and only the first tree was reachable (KZMON-620).

Node property listings. overwatch.props, and the MCP get_node_properties tool over it, now return only the properties a project set on a node — those with a precedence of local. They previously returned the node’s whole property storage, which includes entries no one set.

Adapt a script or tool that reads these listings:

Before	Now
`properties[]` held every storage entry	`properties[]` holds only local values; the rest are counted in `storage`
an entry with `"value":null` meant “storage exists, no value”	such entries are not listed at all; `storage.none` counts them
no way to tell a set value from storage	each entry carries `"precedence":"local"`
`overwatch.props <path>`	unchanged; add `precedence=all` for the old, now-labelled, full listing

Nothing is lost: precedence=all returns every entry, and each one names the precedence level that supplies its value — local, style, modified, classDefault, or none for storage with no input into the value at all. These follow Kanzi’s own property precedence order; see Understanding what overwatch.props reports. The binding field is unchanged and remains independent of precedence — a bound property is usually local, but a resource binding can leave the value coming from the class default (KZMON-633).

Migrating from Kanzi Monitor 1.41.0 to 1.41.2¶

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

Kanzi Monitor 1.41.1 was 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.2¶

Migrating from 1.40.0 is a superset of the 1.41.0 → 1.41.2 path: apply the steps below, then all of the “Migrating from Kanzi Monitor 1.41.0 to 1.41.2” 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.2¶

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

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