Migration guides

Use these guides to update a project from an earlier version of Kanzi Monitor to Kanzi Monitor 1.41.3. Follow the section for the version you are coming from. Each step says what to change or what to know; the linked pages explain the details.

Migrating from Kanzi Monitor 1.41.2 to 1.41.3

Kanzi Monitor 1.41.3 is built for the same Kanzi 4.1 generation as 1.41.2, so no Kanzi engine migration is involved. Each of Kanzi 4.1.0, 4.1.1 and 4.1.2 has its own Kanzi Monitor package: use the package for the Kanzi version your application uses. No configuration key or console command was removed or renamed.

What to change:

  • Breakpoint targets. debug.breakprop refuses a target it used to accept: a vector needs exactly one number per component, an int must fit in 32 bits, and a float must be finite. Update a script or a saved breakpoint that relied on the old reading; it was watching a value other than the one it named. In C++, DebugService::addPropertyBreakpoint() returns 0 for such a target (KZMON-687, KZMON-761).

  • Metaclass listing. overwatch.metaclasses no longer lists the unnamed concept template instantiations (unnamedOmitted counts them). base is never an empty string: it is the nearest named ancestor, or null for a root, and rootCount counts only real roots. Update a client that keyed on an empty base or on the unnamed rows. See Reading the type graph: base classes and mixins (KZMON-586).

  • String values. overwatch.setprop, overwatch.setresourceprop, overwatch.setrenderpassprop, overwatch.setdata, overwatch.dispatchmessage, nodetree.addcomponent, nodetree.setcomponentprop and resource.create refuse a string that is not valid UTF-8. A value that starts with a quote is a quoted value only when one pair of quotes encloses all of it, and a quoted argument must end at its closing quote followed by a space: "a"b is refused. Text that starts with $" is now a string literal; to pass such text as it is, write it as a literal. See Setting any text: the string literal (KZMON-901).

  • Resource addressing. Address a resource by its handle, which every resource listing reports. An index is deprecated, and a reply to a command whose resource was named by index carries deprecation. overwatch.resourceprops and overwatch.setresourceprop, which are new in this release, refuse an index with "error": "Index not accepted": a stale index would name another resource, and for setresourceprop that is a write to the wrong resource that reports success. overwatch.resourceinfo, texturepreview, renderpasspreview, renderpassprops and resourceprops refuse an argument they do not take, and a maxDim that is not a whole number of 0 or more. See Addressing a resource (KZMON-912, KZMON-922, KZMON-945, KZMON-947).

  • profcats. profcats without an argument reports how many profiling categories are enabled, where it answered <No data>. Update a script that parsed the old answer (KZMON-874).

  • Your own plugin on Linux. A plugin of your own that links libkzmonitor.so must export its own createModule. See Integrating Kanzi Monitor into existing projects (KZMON-878).

  • Package manifest. The manifest sidecar beside each platform package is named <package>.delivery_manifest.yaml, where it was <package>.manifest.yaml, and carries manifest_version: 2. Update a pipeline that picks the sidecar up by name or reads its keys (KZMON-775, KZMON-805, KZMON-933).

  • C++ API. RemoteConsole no longer derives from Console. Its constructor takes the connection limit, RemoteConsole(kanzi::Domain* domain, int serverPort, int maxConnections), and its destructor is no longer virtual. Its stream-buffer helpers in the same header changed too: SocketWriteBuf takes an OutboundQueue. Update code that creates a RemoteConsole, uses it as a Console, or uses those helpers directly. findNodeByPath() is removed from kanzimonitor_util.hpp: use findNodeSharedByPath(), which returns a kanzi::NodeSharedPtr (KZMON-823, KZMON-948).

What to know:

  • Linux x86-64 host for |k| 4.1.2. The Kanzi Monitor package for Kanzi 4.1.2 needs a host with glibc 2.35 and GLIBCXX 3.4.30, such as Ubuntu 22.04 or newer, because the Kanzi 4.1.2 engine libraries do. On an older host the plugin fails to load with a version ... not found error naming a GLIBC_ or GLIBCXX_ version. The packages for Kanzi 4.1.0 and 4.1.1 run on the hosts their engines run on (KZMON-979).

  • Console responses are UTF-8. Non-ASCII text in a JSON response arrives as UTF-8. On Windows, and on x86 and x86-64 Linux and Android, each byte used to arrive as its own \u00XX escape. Remove any client workaround that re-decoded those escapes (KZMON-925).

  • Perfetto timestamps. The perfetto writer emits session-relative timestamps, as chrometrace does, and records the base in the trace. A custom tool that needs the engine-clock value adds the base back. See Using the Profiling Trace service (KZMON-690).

  • kzTrace on Android. When Kanzi Monitor cannot resolve the application’s files directory, overwatch.kztrace refuses the capture instead of letting the engine write to /sdcard/Download/. Collect kzTrace output from the application’s files directory, not from /sdcard/Download/, and retry a refused capture once the application’s Java entry point has run. See kzTrace: engine-native tracing (KZMON-764).

Migrating from Kanzi Monitor 1.41.1 to 1.41.3

Apply the steps below, then all of the “Migrating from Kanzi Monitor 1.41.2 to 1.41.3” steps above. Kanzi Monitor 1.41.2 was built for the same Kanzi 4.1 generation, so no Kanzi engine migration is involved.

  • Log buffer access. KanziMonitorLogger::getLog(), which returned a reference to the log container, is removed, because the buffer is now guarded by a lock that a returned reference would outlive. Use:

    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(), which trims to the new cap itself

    withLog() runs your visitor while the lock is held: keep it short, do not store the reference, and do not call back into the logger from it. Only C++ code that reads the buffer directly is affected. See Using the Log service (KZMON-629).

  • Node paths. A path that resolves to no node returns Node not found, where any single-segment path, such as / or /anything, used to answer for the first view root. Address nodes by the path overwatch.nodes reports, which equals the engine’s Node.Path. The unqualified /<rootName>/child form still works (KZMON-620).

  • Node property listings. overwatch.props, and the MCP get_node_properties tool, return only the properties set on the node, those with a precedence of local:

    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; 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 full listing, each entry labelled

    See Understanding what overwatch.props reports (KZMON-633).

  • Screenshot polling. overwatch.screenshot reports a capture that has not completed as "status":"pending", where it said "scheduled". Poll for pending, and treat a status you do not recognize as unfinished. A capture now has a deadline: check framesRendered before using the pixels (KZMON-622).

Migrating from Kanzi Monitor 1.41.0 to 1.41.3

Apply the steps below, then all of the “Migrating from Kanzi Monitor 1.41.1 to 1.41.3” steps above.

  • Performance watcher comparison enum. The WatcherComparison enumerators are renamed: Below to BelowThreshold and Above to AboveThreshold, because X11 headers define the old names as macros. Update C++ code that uses the enum, such as a call to PerformanceService::addWatcher(). The watcher command, the Overwatch JSON, the Web UI and the MCP add_watcher tool still use "below" and "above" (KZMON-504).

  • chrometrace timestamps. The chrometrace writer emits session-relative timestamps, with the first event at 0, and ts and dur as fractional microseconds. Update a custom tool that reads trace files if it relied on absolute or integer values. See Using the Profiling Trace service (KZMON-505, KZMON-506).

Migrating from Kanzi Monitor 1.40.0 to 1.41.3

Apply the steps below, then all of the “Migrating from Kanzi Monitor 1.41.0 to 1.41.3” steps above. Kanzi Monitor 1.40.x is built for the Kanzi 4.0 generation, and 1.41.x for the Kanzi 4.1 generation.

  • Engine SDK. Kanzi Monitor 1.41.x requires a Kanzi 4.1 release. The engine update itself is covered by the Kanzi SDK migration guide (4.0 → 4.1); this guide covers only the Kanzi Monitor steps.

  • Build integration. The application CMakeLists.txt that Kanzi Studio 4.1.0 generates has a ready-made if(KANZI_LINK_KZMONITOR) block: enable Kanzi Monitor with -DKANZI_LINK_KZMONITOR=ON. The manual block in Integrating Kanzi Monitor from source code and Integrating Kanzi Monitor as a prebuilt library is needed only for a project whose CMakeLists.txt does not have it.

  • Android packaging. Kanzi Monitor no longer ships an AAR and has no Java API. Remove a dependency on the monitor-* AAR, and build libkzmonitor.so into your APK with -DKANZI_LINK_KZMONITOR=ON on your kanzinative module. See Integrating Kanzi Monitor as a prebuilt library.

  • Scene-graph resolution. Remove any setApplication (C++) or setNativeRuntime / setNativeApplication (JNI) calls, the NodeRegisteringScreenEnabled key, and the registerRoot / registerNativeViewRoot hook; the ApplicationReference class is removed. Kanzi Monitor finds the scene graph through Domain::getScreens(), with no injection or registration.

  • Commands. appquit is removed: use quit. appfpsinfo is renamed fpsinfo, and its header is FPS Info :. perfinfolevel is always available, and its header is PerformanceInfo level:. The appfps metric is removed: use fps. Update scripts and performance watchers that use the old names or headers.

  • Custom trace writers. SampleCollector::registerWriterTask() and SampleCollector::clearWriterTasks() are removed. Register a writer with TraceWriterRegistry and select it by name:

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

// 1.41
#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");

    ActiveWriters = mywriter in kanzimonitor.cfg selects it too, if it is registered before the Trace service initializes; otherwise activate it in code or with overwatch.activatewriter. See Using the Profiling Trace service.

  • Android trace output location. Trace files go to the application’s internal files directory, typically /data/user/0/<package>/files/, instead of /sdcard/. Drop the storage permissions if you used them only for trace output, and fetch traces with adb shell run-as <package>. See Using the Profiling Trace service.

  • Configuration key. The frame-duration trigger key is spelled WritingOnFrameDurationThreshold. The misspelling WritingOnFrameDurationTreshold still works but is deprecated.

  • Graphics API call logging. The graphicslog and overwatch.graphicslog commands and the set_graphics_logging and get_graphics_logging MCP tools are removed: Kanzi 4.x has no engine API for them. Drop scripts that use them.

Migrating from Kanzi Monitor 1.9.x to 1.41.3

Migrating from 1.9.x is a superset of the 1.40.0 → 1.41.3 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.3” steps above, which in turn chain through the 1.41.0, 1.41.1 and 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.3

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