Release notes

Here you can find the release notes for Kanzi Monitor.

1.41.2

Compatible with Kanzi 4.1.0.

A maintenance release on the Kanzi 4.1 generation, with four feature additions. It closes three defects that could take down the host application — a log buffer mutated from several threads without a lock, console streams freed while the main thread was writing through them, and an exception from any console command handler ending the process — and corrects node path resolution on hosts with more than one view tree, trace output on Android, and what Kanzi Monitor reports about the device’s graphics capabilities, its formats, and a node’s properties. It also adds runtime introspection: four commands reporting the loaded kzb files and the property, message and metaclass vocabulary an application was built with, reachable from the console, a new Web UI Engine tab, and four MCP tools. Render pass properties become readable and settable, so the Web UI Render Passes view is interactive rather than read-only. A capture service records a bounded sequence of screen frames into memory for replay after the fact. And property breakpoints break, log, screenshot, or run a console command when a node property reaches a value, with a new Web UI Debug tab and MCP tools.

No configuration key changed and no existing command was renamed. Three items need attention when you update: a removed C++ accessor on KanziMonitorLogger, node paths that no longer fall back to the view root, and a narrower default listing from overwatch.props. See Migration guides.

New features

Runtime introspection of loaded kzb files and the type vocabulary

• Four commands report what a running application actually loaded and the vocabulary it was built with: overwatch.kzbfiles lists the loaded kzb files and, on request, their entries with byte sizes; overwatch.propertytypes and overwatch.messagetypes list the registered property and message types, including project-authored ones; and overwatch.metaclasses lists the registered metaclasses. All support filtering and paging. See Using the Overwatch service (KZMON-635).

Engine tab in the Monitor Web UI

• The Web UI has an Engine tab for browsing the four listings above, with a sub-tab per registry and filtering and paging in the panel rather than in command arguments (KZMON-636).

MCP tools for the introspection commands

• get_kzb_files, get_property_types, get_message_types and get_metaclasses expose the same listings as typed MCP tools, so an agent receives structured data rather than console text (KZMON-637).

Render pass properties are readable and settable

• overwatch.renderpassprops reports a render pass’s properties and overwatch.setrenderpassprop sets one, with the same reporting rules as node properties. The Web UI Render Passes view and the MCP get_render_pass_properties / set_render_pass_property tools use them, so the view is interactive rather than read-only. See Using the Overwatch service (KZMON-640).

Frame-sequence capture

• capture.start records a bounded sequence of screen frames into memory as a keep-last-N ring, so you can stop after something interesting happens and replay what led up to it; capture.stop, capture.status, capture.manifest and capture.frame drive and fetch it. A Web UI Capture tab records, scrubs and plays the sequence back with a filmstrip, and MCP tools expose the same surface. The service reports what recording costs in framerate. See Using the Capture Service (KZMON-638).

Property breakpoints

• Property breakpoints (debug.breakprop and siblings): break, log, capture a screenshot, or run a console command when a node property reaches a value. The condition is evaluated by a Kanzi property notification handler, inside the assignment that changed the property, so with a debugger attached execution stops on the code that wrote the value rather than a frame later. Conditions cover float, int, bool, string and the vector types; a breakpoint can fire on every Nth change or once only. See Using the Debug service.

• A breakpoint can be set on a property that has no value yet, and fires on the first write to it: registering creates the node’s property storage entry rather than requiring one.

• The commands use a debug. prefix of their own, and are enabled by the new ServiceDebugEnabled setting (default 1). The Overwatch commands report on the application; a breakpoint intervenes in it, so an application can expose the introspection surface without also allowing a debugger trap and a console command run from inside a property write.

• The Monitor Web UI gains a Debug tab for setting breakpoints and viewing the screenshots they capture, and the MCP server exposes the command set as seven tools.

Changes

ServiceDebugEnabled now works with the Overwatch service switched off

• The debug.* commands registered from inside the Overwatch service, which the plugin only brought up when ServiceOverwatchEnabled was set. ServiceDebugEnabled = 1 therefore did nothing at all with Overwatch off, and the setting could only ever narrow an already-enabled Overwatch. Breakpoints are now their own service, so the setting enables and disables them in both directions, as its name says (KZMON-650).

• No command name, configuration key or default changes. The one behavioral difference is that the screenshot breakpoint action needs a service that owns the framebuffer: with Overwatch disabled it reports that no capture source is available instead of capturing. The other six commands are unaffected. To record the frames leading up to a breakpoint instead, attach capture.stop to it with debug.breakcommand. See Using the Debug service.

The Web UI Trace tab fetches load; Download saves

• The Trace tab’s fetch buttons no longer write a file: Fetch .perfetto-trace (and the JSON auto-fetch after a capture) load the trace into memory for View in Perfetto, and a single Download button — labeled after the loaded format — is the explicit save action for either format. Previously Fetch .perfetto-trace saved the file directly on every click. The tab also gains a Format selector that shows and switches the active trace writer set (chrometrace, perfetto, or both), and its auto-fetch follows the format the capture actually produced, so a perfetto-only configuration works from Capture Trace alone (KZMON-688).

Composite property values must now parse completely

• overwatch.setprop and overwatch.setrenderpassprop now reject a Vector2, Vector3, Vector4, Color, SRTValue2D or SRTValue3D value that has the wrong number of components or anything left over, with the same error shape the int and float paths already used. Previously the value was read with sscanf and a partial match counted as success: 1,2,3 set a Vector2 to (1,2) and 1,0,0,junk set a colour to (1,0,0), both answering success: true. A script passing an over-long or malformed value was being told it had worked; it now gets an error naming the expected format. Color still accepts three components as well as four (KZMON-660).

• The value field of a successful response now reports what was stored rather than what was typed, with the input echoed alongside it as requested. A colour given three components therefore reports the four that were stored, so a caller can see that alpha defaulted (KZMON-660).

• Setting a property whose type is not registered now says so, instead of reporting a format error for a type that was guessed from the value. Asking for a colour on an unregistered name used to answer Invalid int format, use a whole number (KZMON-660).

Node paths that do not resolve no longer fall back to the view root

• A node path that names 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 the view root when given a path that pointed nowhere. Address nodes by the path overwatch.nodes reports: it is the engine’s own Node.Path, and it now round-trips exactly. Update a script that relied on the fallback, or that addresses a node by a name the node no longer has (KZMON-620).

Log buffer accessor removed from KanziMonitorLogger

• KanziMonitorLogger::getLog() is removed. It returned a reference into the log container, and a reference outlives any lock the container could take, so the accessor could not be made safe by locking behind it. Reads now go through withLog(), which runs a visitor while the lock is held; getEntryCount() returns the entry count. Only C++ code that reads the buffer directly is affected — the loginfo and overwatch.logs commands, the Web UI Logs tab, and the MCP get_logs tool are unchanged. See Migration guides (KZMON-629).

Notable fixes

• Fixed every node path overwatch.nodes reports being rejected by the commands that resolve one – overwatch.props, overwatch.setprop, and their Monitor Web UI and MCP equivalents – on a host where a Kanzi Screen has a parent, such as a service-hosted or droidfw application. The reported path is the engine-canonical Node.Path, which on such a host carries a segment above the enumerated view root (for example /client1/Screen/Root), while the resolver stripped exactly one leading segment and anchored on the first view root: the Monitor Web UI rendered the node tree and then could not inspect any node in it. Paths now resolve against every view root’s own canonical path, so every reported path round-trips, and on a multi-view host each tree is addressable by its own prefix – previously only the first tree was reachable at all. The unqualified /<rootName>/child form still works, for single-view hosts and existing scripts (KZMON-620).

• On Android, the file trace writers (chrometrace, perfetto) failed with Unable to open file because the trace output directory resolved empty: the reflective ActivityThread.currentApplication() lookup returned null in the plugin’s initialization context, leaving the SampleCollector output directory empty so writers opened a bare relative path against the process working directory. Kanzi Monitor now resolves the app-internal files directory from the engine-held Android Context / JavaVM, using the reflective lookup only as a fallback. If no writable files directory can be resolved at all – for example when Kanzi Monitor initializes before any Java entry point has run – the file writers are no longer activated and Kanzi Monitor logs an actionable error naming them instead of throwing on the first write; stream traces with the perfetto-producer writer in that case (KZMON-646).

• On Android, capturing a kzTrace (overwatch.kztrace, the Web UI Trace tab’s “kzTrace (Engine)” option, the MCP capture_kztrace tool) required the host application to declare and be granted a storage permission – and failed even then whenever the Monitor trace directory had been resolved, because Kanzi Monitor passed an absolute path to the engine’s logTraceToFile(), which on Android prepends its own output directory (/sdcard/Download/ by default), producing a path under a directory that does not exist. Kanzi Monitor now points the engine’s tracing subsystem at the same app-internal files directory its own writers use – regardless of which services are enabled – and passes a bare filename, so kzTrace needs no storage permission, lands next to the Monitor traces, and overwatch.fetchkztrace returns it. The permission hint is gone from the error path and the corresponding known issue is removed (KZMON-677).

• Fixed the log buffer being mutated from several threads with no synchronization. writeOverride() appended and trimmed the buffer from whichever thread logged, while readers walked the same container from the main thread and from console threads; concurrent structural mutation corrupts the container’s links, and a reader walking it while a writer trims the head dereferences freed memory. The buffer is now guarded by a mutex, and setMaxEntries() trims to the new cap itself rather than leaving the console thread to pop the excess from outside the class (KZMON-629).

• Fixed the remote console recreating its read buffer, write buffer, and both streams on every accepted connection, on the reader thread, while the main thread could still be writing through the old ones — a write through freed memory, reachable in ordinary use because the MCP server opens a connection per interaction. The four objects now live as long as the console does and only the socket handle is swapped (KZMON-629).

• Fixed the MCP server returning oversized responses in full. Its large-response guard counted lines only, so a single-line Overwatch JSON payload — a scene tree, a resource listing, or a trace — passed through whole and flooded the client’s context. The guard now bounds the preview by characters as well, and reports the total size of what it truncated (KZMON-631).

• Fixed the standalone example application solution linking a kzmonitor configuration that did not match the one being built, without reporting the mismatch. The configuration ordering the solution requires is now documented at the point where it matters, and a mismatch is reported rather than silently linked (KZMON-632).

• Fixed overwatch.graphics naming only 12 of the engine’s 184 graphics formats and printing Format_<n> for the rest, so a 24-bit sRGB background reported as Format_11 and every compressed format (ETC2, ASTC, BCn, PVRTC) was unnamed. Monitor now asks the engine for the name instead of keeping its own partial copy (KZMON-634).

• Fixed overwatch.status under-reporting the device’s graphics capabilities. The feature table was maintained by hand and had fallen three behind Kanzi 4.1, which never reported BindlessResources, SeparateDepthStencilLayouts or TimestampQuery. All features the engine exposes are now reported, and a static_assert fails the build if the engine’s feature enum changes, so the report cannot drift silently at the next baseline. The table is specific to the Kanzi generation being built against (KZMON-634).

• Fixed an exception thrown by any console command handler terminating the host application. A malformed argument was enough — overwatch.setdata <ds> /vehicle/speed notanumber let an exception escape std::stoi, the handler, and the task dispatcher, and reached the application framework’s top-level handler, which ended the process; the client received zero bytes. Command dispatch now contains exceptions and answers with a JSON error, so a throwing handler costs one failed command instead of the application. The response terminator moved into a destructor, so a throwing handler can no longer leave a client waiting for a terminator that never arrives. The three reachable numeric conversions also validate their input individually, naming the value rejected and the type expected (KZMON-630).

• Fixed overwatch.setprop guessing a property’s data type from the shape of the value string, which made vector-typed properties impossible to set on a node that had no storage for them already. The type now comes from the property type registry (KZMON-633).

• Fixed overwatch.props and the MCP get_node_properties tool reporting a node’s property storage as though it were locally-set values, so entries no one set appeared with a null value while properties the project had set could be missing. The listing now returns local values by default, each labelled with its precedence, and counts the rest; precedence=all returns every entry. See Migration guides (KZMON-633).

1.41.1

Compatible with Kanzi 4.1.0.

A maintenance release on the Kanzi 4.1 generation: it corrects what the distribution packages contain, trace and property serialization, main-loop task teardown, and an on-screen rendering defect. No configuration key or command name changed, and the console, JSON, and Web UI command surfaces are unchanged. Two items need attention when you update — a C++ enumerator rename and the chrometrace timestamp format. See Migration guides.

New features

Offline HTML documentation in every package

• Offline HTML documentation now ships in every platform package, not only the Windows package. Open doc/html/index.html in the package to read it without network access (KZMON-392).

Composition-target render pass in the example application

• The example scene now includes a composition-target render pass, so the Overwatch render-pass tools (overwatch.renderpasses, overwatch.framebuffers, overwatch.renderpasspreview and their Web UI and MCP equivalents) have a real composition target to inspect out of the box (KZMON-509).

Cubemap in the example application

• The example scene now uses the cube-mapped material it ships, so resinfo and overwatch.resourceinfo report a real CubeMap and per-face texture preview — in the Web UI Resource Viewer, overwatch.texturepreview, and the MCP get_texture_preview tool — has actual faces to show (KZMON-524).

Changes

Performance watcher comparison enumerators renamed

• WatcherComparison::Below and WatcherComparison::Above are renamed to BelowThreshold and AboveThreshold, because X11 headers — pulled in by the Kanzi engine on linux_x11 — #define Below and Above as integer constants and clobbered the old enumerator names. Only C++ code that uses the enum directly is affected; the watcher command, the Overwatch JSON, the Web UI, and the MCP add_watcher tool keep the "below" / "above" strings. See Migration guides (KZMON-504).

Notable fixes

• Fixed profiling traces being rejected by the Perfetto trace viewer (trace_sorter_negative_timestamp_dropped) on some platforms and uptimes; the chrometrace writer now emits session-relative timestamps, so every trace starts at 0 and loads correctly. See Migration guides (KZMON-505).

• Fixed sub-microsecond profiling scopes rendering as zero-duration events in the trace viewer; trace ts and dur are now emitted as fractional microseconds. See Migration guides (KZMON-506).

• Fixed node-property JSON being rejected by the Monitor Web UI when a property held a non-finite float (for example the infinite GridListBoxConcept.CalculatedOffset of a not-yet-scrolled list item); non-finite floats are now serialized as null in Overwatch JSON output. See Using the Overwatch service (KZMON-507).

• Fixed the “Frames per second” trace counter recording implausible values for zero or near-zero duration frames, typically at startup; a single such sample stretched the trace viewer’s counter auto-scaling and flattened every real FPS sample. Such samples are now skipped (KZMON-304).

• Fixed the quit command falsely reporting executed successfully on Android, where the platform owns the process lifecycle and ending the Kanzi main loop cannot terminate the application; quit now takes no action on Android and reports that it is not supported. Windows, Linux, and QNX behaviour is unchanged. See Using the Command Processor service (KZMON-508).

• Fixed the Monitor UI “Colored overlay” screen (basicui 1) painting a flat, near-opaque wash that hid the application scene; it renders as the intended light tint again (KZMON-305).

• Fixed Kanzi Monitor services leaving their main-loop tasks and timers registered with the MainLoopScheduler after shutdown, and adding a second copy of every task when a service was re-initialized; services now remove exactly the entries they registered, and nothing registered by the host application, another plugin, or the Kanzi Engine is touched. The MainLoopTaskSet helper they use ships in the plugin’s include/ directory for extensions that register their own tasks. See Using the Performance service (KZMON-313, KZMON-314).

• Corrected the “Adding custom metrics” example in Using the Performance service, which registered a recurring main-loop timer without keeping the token needed to remove it, passed an undeclared profiler value to updateMeasureAndStore(), and did not say that value must outlive the timer sampling it (KZMON-314).

• Corrected the description of node-property reporting: overwatch.props and the MCP get_node_properties tool return a node’s locally-set property values, not all of a node’s properties. The behaviour is unchanged — the console help text, the reference tables, and the MCP server documentation now state what is actually returned (KZMON-515).

• Fixed the vendored Perfetto SDK’s LICENSE and attribution files being absent from the distribution packages; the plugin, source-only, platform CPack, and Conan packages now all carry them — under third_party/perfetto/ in the archives, and licenses/perfetto/ in the Conan package (KZMON-319).

• Fixed the source distribution package omitting the vendored Perfetto SDK sources, which made configuring it with -DKZMONITOR_PERFETTO_PRODUCER=ON fail; the source package now includes third_party/, so the perfetto-producer writer builds from source (KZMON-319).

• Fixed the Linux and QNX CMake platform packages not shipping the plugin source (src/), although these packages are intended to be source-inclusive; the Windows and source-only packages were unaffected (KZMON-320).

• Fixed incorrect console configuration key names in the RemoteConsoleClient, SerialConsoleClient, and MCP server READMEs; the documented keys are now RemoteConsoleEnabled, SerialConsoleEnabled, and RemoteConsolePort, each with its actual default value (KZMON-343).

1.41.0

First release of Kanzi Monitor for Kanzi 4.1. Compatible with Kanzi 4.1.0. A source-only distribution package is available for building the plugin from source against any supported Kanzi 4.1.x version.

Features

Kanzi Monitor introspects a stock Kanzi 4.1 application out of the box: it resolves the host scene graph and frame timing through the Kanzi 4.1 Domain (Domain::getScreens() / Domain::getFramesPerSecond()), with no injected Application or host-side registration.

Command Processor Service

• Local console for interactive command-line access over stdin/stdout, a remote console over TCP sockets, and a serial console over serial ports (UART; Windows COM ports and POSIX serial devices).

• Built-in commands for application control, scene graph inspection, and diagnostics, plus support for custom application-defined commands. kzinfo reports the build configuration (Debug, Profiling, or Release).

Trace Service

• Profiling data collection with configurable sample buffers and collection intervals.

• Output driven by a named writer registry: writers register under a name and are selected through the ActiveWriters configuration key (default chrometrace), switchable at runtime via overwatch.writers / overwatch.activatewriter / overwatch.deactivatewriter. Built-in writers:

  • chrometrace — Chrome Trace Format JSON.

  • perfetto — native Perfetto protobuf (.perfetto-trace): typed counters and debug annotations, the canonical input format for Perfetto UI and Android Performance Analyzer, via a hand-rolled encoder with no external dependency.

  • perfetto-producer — streams events to the platform tracing daemon (Android traced, Linux perfetto) so Kanzi work appears alongside ATrace and SurfaceFlinger in a single system timeline. Requires building with -DKZMONITOR_PERFETTO_PRODUCER=ON (Android binaries ship with it on).

• Configurable automatic trace output on exit, on timer, or when frame duration exceeds a threshold.

UI Service

• On-screen overlay with basic, report, and control screen modes; configurable font scaling for high-DPI devices; touch and key input.

Log Service

• In-memory log buffer with on-screen presentation; the buffer size is configurable at runtime (overwatch.logconfig).

• Console access to log entries, category filtering in the Monitor Web UI, and KanziLog trace pipeline diagnostics for troubleshooting missing log entries.

Performance Service

• Runtime performance statistics and counters with the PerformanceInfo profiling category.

• Performance metric watchers that trigger commands when thresholds are crossed.

Overwatch Service

• JSON-based remote introspection of the scene graph, resources, rendering, data sources, and performance; scene graph browsing with configurable depth limiting; property querying and modification.

• Resource inspection with CPU/GPU memory usage and metadata, including texture type / cubemap descriptors (type, face count, dimensions, format, mipmap levels) through resinfo and overwatch.resourceinfo.

• Texture and render-pass output preview, with per-face cubemap preview (overwatch.texturepreview face=<n>); screenshot capture through scheduled framebuffer readback.

• Font and glyph cache inspection (fontinfo / overwatch.fonts / overwatch.glyphcachepreview): font identity, style, metrics, and a live glyph-atlas preview, plus runtime glyph cache size control (overwatch.setglyphcachesize) for pressure testing.

• Real-time performance metrics (FPS, frame times, render statistics); DataSource inspection including DataObjectList nodes; log entry access and trace control; graphics backend information; build configuration through overwatch.status.

Platform support

• Windows (MSVC 2022)

• Android

• QNX 710

• Linux

Tools

• Monitor Web UI — browser-based GUI for remote inspection and debugging: live scene graph browsing, property editing, resource and texture preview, screen capture, render pass visualization, performance monitoring, and trace capture. This release adds a Fonts tab (font identity/metrics, live glyph-atlas preview, editable glyph cache size), a View in Perfetto button on the Trace tab, a Logs category filter with an editable buffer size, and Screen-tab overlay controls (PerformanceInfo level, Monitor UI visibility, BasicUI screen, font scale). All platform packages include a prebuilt standalone executable.

• MCP Server — Model Context Protocol server that exposes the Overwatch command set as structured tools for AI assistants such as Claude Code and Claude Desktop. New this release: get_fonts, get_font_glyph_cache_preview, set_glyph_cache_size, get_log_config / set_log_buffer_size, and a face parameter on get_texture_preview.

• RemoteConsoleClient — command-line TCP client for the remote console. Prebuilt for Windows and Linux.

• SerialConsoleClient — command-line serial client for the serial console. Prebuilt for Windows and Linux.

Example project

• The example application under examples/monitor_example/ is compatible with, and uses, the application templates from Kanzi 4.1.0. See the Kanzi 4.1.0 SDK documentation for details on the new template structure.

Changes since 1.40.0

A “what changed since the previous minor” recap. This is a notification only — see Migration guides for how to adapt, and the main docs for how to use.

• Added: font and glyph cache inspection; runtime glyph cache size control; Perfetto trace output (perfetto / perfetto-producer) and an embedded Perfetto UI in the Web UI; cubemap / texture-type resource inspection; build-configuration reporting; Web UI log category filtering; runtime log buffer size control. (See Features above.)

• Removed: the Application-injection API — setApplication (C++), the setNativeRuntime / setNativeApplication JNI handshakes, the NodeRegisteringScreenEnabled override, and the registerRoot / registerNativeViewRoot view-root hook (the scene graph is now resolved via Domain::getScreens()); the Android Monitor AAR (Kanzi Monitor exposes no Java API); the appfps metric and the appquit command (use fps and quit).

• Changed: trace output is selected through the ActiveWriters writer registry — the public SampleCollector::registerWriterTask() / clearWriterTasks() symbols are removed (register via TraceWriterRegistry); the app-prefixed commands are retired (appfpsinfo → fpsinfo).

• Fixed: the Web UI “Connected” indicator no longer stays green after the application exits; RemoteConsole sets SO_REUSEADDR so port 56000 is reusable immediately after a restart; screenshot-capture timeouts report an actionable hint and take_screenshot completes in a single call; texture-preview GPU readback uses the texture’s native pixel format (fixing corrupted HDR and cubemap previews); Android trace output writes to the app’s internal storage (Context.getFilesDir()) instead of /sdcard/, removing the external-storage permission requirement; the frame-duration trigger key is now spelled WritingOnFrameDurationThreshold (the 1.40.0 misspelling WritingOnFrameDurationTreshold remains a deprecated alias); the non-functional graphics API call logging commands (graphicslog / overwatch.graphicslog and the set_graphics_logging / get_graphics_logging MCP tools) — carried over from the 1.9.x line but dead on Kanzi 4.x, which dropped the underlying engine API — are removed, so they no longer appear available when they cannot work.

See also

Migration guides

Known issues