Using the Monitor Web UI

The Monitor Web UI is a browser-based graphical interface for remotely inspecting and debugging Kanzi applications. It connects to the Overwatch service through a Python WebSocket bridge and provides visual tools for browsing the scene graph, editing properties, previewing textures and screenshots, monitoring performance, and capturing traces.

The tool is located in tools/monitor-web-ui/. See tools/monitor-web-ui/README.md for the full reference.

Requirements

  • Python 3.7 or later

  • websockets library: pip install websockets

  • For serial and UART connections: pip install pyserial-asyncio-fast

Starting the Monitor Web UI

To start the Monitor Web UI:

  1. Make sure that the Overwatch service is enabled (enabled by default). To disable property editing, set OverwatchPropertyChangeEnabled = 0 in kanzimonitor.cfg.

  2. Start the Kanzi application with Kanzi Monitor.

  3. Start the WebSocket bridge:

    cd tools/monitor-web-ui
    pip install websockets
    python bridge.py
    

    The bridge connects to Kanzi Monitor at 127.0.0.1:56000 and serves the web UI at http://localhost:8765.

  4. Open http://localhost:8765 in your browser.

Connecting to remote or embedded targets

To connect to Kanzi Monitor running on a different machine:

python bridge.py --monitor-host 192.168.1.100

To connect through serial and UART for embedded targets with SerialConsoleEnabled = 1:

pip install pyserial-asyncio-fast
python bridge.py --serial-port COM3
python bridge.py --serial-port /dev/ttyUSB0 --baud-rate 921600

Features

The Monitor Web UI provides these features:

  • Node Tree – Live scene graph with expand/collapse, auto-refresh, and node type icons.

  • Dispatch message – On the Nodes tab, above the properties: dispatch a message from the selected node. Pick the message type from the list, fill in the arguments you want (one row per declared argument; the Web UI checks only the number of components of a composite value, and the application checks the rest and names any argument it refuses), and Dispatch. The first dispatch of a message asks for confirmation and shows its routing and which arguments will be left at their default; dispatching the same message again does not ask. The result line says whether a handler marked the message handled, and a refusal says why. See Dispatching a message.

  • Property Inspector – View and edit properties on selected nodes. A string property is edited in a multi-line text box, so its value can hold line breaks; emptying the box clears the string. A Resource-typed property shows the resource it references, with its class, and takes a resource URL or a ResourceID; Clear releases the reference, and setting the URL back restores it. See Resource-typed properties.

  • Resource Viewer – Browse resources in two views. Loaded shows overwatch.resources, the resources that have a URL, and All shows overwatch.allresources, every resource the ResourceManager holds, with a name filter. In Loaded, the count and the CPU and GPU totals above the table cover every resource the manager holds, so they can exceed the rows listed; All lists the rest. See Which resource list to use. Both views show texture type details (including cubemap face count), texture preview, per-face cubemap preview (all six faces shown as a thumbnail strip, click to enlarge), GPU readback, full-resolution toggle, and download (PNG and Raw RGBA). The toolbar reports the ResourceManager memory strategy and lets you switch the default for resources acquired from then on. Read it before reading a Purge Resources result; after a switch, a purge covers resources acquired under both strategies. See The memory strategy behind a purge. The toolbar also takes a URL and an Acquire button to force a resource into existence, and each row with a URL offers unregister, which drops the URL association so the next acquire rebuilds the resource — the way to pick up a file:// asset you edited on disk. Each URL listed on the Engine tab’s KZB sub-tab is marked loaded or not, from an unfiltered overwatch.allresources, which counts a URL as loaded while it is registered: a URL that is not loaded has an acquire action for the same purpose, and a loaded one has unregister. See Forcing a resource into existence, and letting go of one. Selecting a resource also lists its properties in the viewer, editable in place with the same rows the Nodes tab uses, for any resource that has them: brushes, materials, render passes. See Reading and setting properties on any resource.

  • Performance – FPS and frame timing metrics, rendering statistics, GPU object counts, staging buffer usage, configurable performance watchers, auto-refresh. Includes a SuspendWhenIdle status indicator and toggle. When SuspendWhenIdle is active, the application only renders on input or state changes, which affects FPS measurement accuracy.

  • Screen Capture – Screenshot with full-resolution toggle and download. Inspect and download framebuffer previews. Framebuffer captures – the screenshot, the Capture tab’s frames, breakpoint captures – are oriented from the rowOrder each response reports rather than from a convention compiled into the browser. Kanzi Monitor reports "bottom-up" on every backend today, so if one ever stored its rows the other way round the plugin would have to learn that first; what the reported field buys is that the Web UI, the MCP server and your own clients then need no change of their own. Texture and render-pass previews carry no such report and follow the Flip vertical checkbox, which is flipped by default to match screen orientation. The moment you change that checkbox it takes over for every image, reported or not, and the images already on screen are corrected to match – so a host that misreports its row order is still yours to fix. Overlay controls for the PerformanceInfo level (perfinfolevel), Monitor UI visibility (ui), BasicUI screen selection (basicui), and font scale (fontscale). Controls auto-detect which commands are available. Note that when the Monitor UI overlay is visible, it captures touch input from the application.

  • Capture – Record a bounded sequence of screen frames into memory as a keep-last-N ring: Record arms it, Stop freezes it, Fetch frames retrieves what the ring holds, and Play steps or plays the frames back as a filmstrip you can scrub and download. Drives the capture.* commands. See Using the Capture service.

  • Render Passes – Render pass tree with CompositionTarget preview and download (PNG and Raw RGBA). Selecting any pass shows its properties, editable in place with the same rows the Nodes tab uses. Turning RenderPass.Enabled off and re-reading the preview of the composition target above it shows what that pass contributes.

  • Debug – Set property breakpoints and view the screenshots they capture. Add a breakpoint by node path, property name, value and optional hit count; list, refresh and clear the ones already set. A breakpoint on a property the node has no value for yet is labeled Dormant until the first write to it. Drives the debug.* commands. See Using the Debug service.

  • DataSources – Inspect and edit DataSource and DataObject trees. A string data object is edited in a multi-line text box, as a string property is. DataObjectList nodes display an item count badge and expand to show individual list items as tree children.

  • Fonts – Browse active FontRuntime instances with font identity, style definition, glyph cache state, font metrics, and glyph atlas texture preview. Edit the glyph cache texture size for newly created caches. Shows an informational message when the node tree is not available.

  • Trace – Capture and view profiling traces with summary stats and download. Use the Trace Source selector to switch between Monitor Profiling (all builds, with engine-internal instrumentation in Profiling builds) and kzTrace (Debug/Profiling builds), and the Format selector to see and switch the active trace writer (chrometrace, perfetto, or both — the runtime’s writer set, re-read on every Trace-tab entry and after a change from this tab). Capture Trace fetches whichever format the capture actually produced: the runtime reports the written filename and the tab routes on its extension, so a perfetto-only configuration works end to end without touching the fetch buttons. A new capture clears every cached trace display, and a fetch that serves a file that cannot be the one the capture wrote — an older same-format trace, or a JSON when the capture produced a .perfetto-trace — is called out in the status line instead of shown as current. The Fetch .perfetto-trace button retrieves the native Perfetto protobuf file — the bridge ships the binary as base64 over the line protocol and the UI decodes and holds it in memory; a single Download button (labeled after the loaded format) is the explicit save action for either format. The View in Perfetto button opens the most recently fetched trace directly in Perfetto UI (new browser tab) via Perfetto’s official postMessage embedding protocol; trace bytes stay in your browser. The button works for both chrometrace JSON and .perfetto-trace formats and prefers the binary one when both are loaded. The Profiling Categories card lists every profiling category Kanzi Monitor can find (kzTrace categories are separate), with a checkbox to enable or disable each one, a filter field (ProfilingCategoryFilter syntax, for example *=off;MainLoop=on) and a Reset button that returns every category to its code default and applies the startup filter again, a defined state rather than an undo. A disabled category records nothing, so this decides what a capture can contain; see Choosing which profiling categories are recorded. The kzTrace Categories card beside it lists the kzTrace categories, with their descriptions and ids. It is read-only, because Kanzi 4.1 cannot switch them, and in a Release build it says that kzTrace is not available; see Listing the kzTrace categories. The Heap Profile (Android) card records a native heap profile of an Android application; see Recording an Android heap profile.

  • Logs – Log entries with severity and category filters, live auto-refresh, editable buffer size, and download as TXT.

  • Engine – Runtime introspection of what the application was built with, in four views: KZB Files, Property Types, Message Types and Metaclasses. Filter any view by name and cap the number of rows returned. Drives the introspection commands the Engine tab shares with the MCP server. Under Kanzi Studio Preview, KZB Files does not list the project being authored: Kanzi holds the kzb of each patch from Kanzi Studio only while it applies the patch. The project’s loaded resources are still in the Resource Viewer, in both views, and reachable by URL and handle; acquiring one that is not loaded, including after unregister, fails until the next patch. An exported kzb that an application loads is listed as usual. See kzb files. In Metaclasses, each class lists its base class and, in the Mixins column, the concepts mixed into it, which declare property and message types for the class without being on its base chain. The runtime leaves out the unnamed concept template instantiations, and a note above the table says how many. See Reading the type graph: base classes and mixins. Each metaclass row has a Schema button that lists the property and message types the class declares across its base chain and its mixed-in concepts, each attributed to the class that declares it, with the walk that produced the union. That differs from the row’s own counts, which cover the class alone: Kanzi.TextBlock3D declares 2 property types itself and 65 with its base chain and concepts. Neither is everything that affects a node of that class: attached properties and inherited values are declared by other classes. See What a class declares, in one call.

  • Graphics – The GPU Info panel shows the backend, device, API version and driver version, the Color Workflow the application renders in and the Surface Color Space in effect, and Features lists the device features. See Color workflow and surface color space.

  • Interactive Console – Send arbitrary commands to Kanzi Monitor.

Using the standalone executable

All platform packages include a prebuilt standalone executable monitor-web-ui-win64.exe under tools/monitor-web-ui/dist/. Double-click to launch. The browser opens automatically.

To rebuild it from source:

cd tools/monitor-web-ui
build_exe.bat

This creates dist/monitor-web-ui.exe (approximately 10-15 MB).

Command-line options:

monitor-web-ui.exe --monitor-host 192.168.1.100    Connect to remote Monitor
monitor-web-ui.exe --serial-port COM3               Connect through serial/UART
monitor-web-ui.exe --no-browser                     Do not auto-open browser

Understanding the architecture

                                                     TCP (default)
+-----------------+     WebSocket      +-----------------+<--------------->+-----------------+
|   Web Browser   |<----------------->|   bridge.py     |  localhost:56000|    Monitor      |
|   (index.html)  |   ws://localhost   |   (Python)      |                 |  (Kanzi Plugin) |
+-----------------+       :8765        +-----------------+<--------------->+-----------------+
                                                        Serial (--serial-port)
                                                         COM3 / /dev/ttyUSB0

The web UI sends overwatch.* commands through WebSocket. The bridge forwards them to the Kanzi Monitor console (TCP or serial) and returns JSON responses.

The bridge listens on localhost only, and accepts a WebSocket only from the web UI it serves: http://localhost:<port>, http://127.0.0.1:<port> or http://[::1]:<port>. A browser does not apply the same-origin policy to a WebSocket, so without this check any web page open in the browser could connect to the bridge and send Kanzi Monitor commands. A connection from another origin is refused with HTTP 403, and the bridge prints the refused origin. Open the web UI from the bridge’s address, not from a copy of index.html. A program that connects without an Origin header, such as a script using a WebSocket library, is accepted.

Recording an Android heap profile

The Heap Profile (Android) card on the Trace tab records where the application allocates native memory, with call stacks, using Android’s sampling heap profiler heapprofd. Set the options below and click Capture Heap Profile. When the capture ends, View in Perfetto opens the result in Perfetto UI, and Download saves it. heapprofd is a system service that only the device shell can start, so the bridge does the capture: it runs adb on the machine the bridge runs on, and the device must be attached there over USB or adb-over-network. It is not available over a serial connection.

  • Mode. Running app records allocation churn during the capture; in Perfetto, set Measure to Total Malloc Size, because memory allocated and freed during the capture shows only there. From launch restarts the application under the capture, so the profile shows what it holds after startup in the default Unreleased Malloc Size view. The Web UI loses its connection to Kanzi Monitor while the application restarts and reconnects by itself.

  • Seconds and Sampling. Sampling is the mean number of bytes between two recorded allocations. A lower value records more call stacks and costs the application more.

  • Include kanzi.* tracks. Adds the Kanzi tracks to the same trace, so the heap snapshots, taken every 5 seconds, sit on the same timeline as the frames. For the capture, the bridge streams Kanzi Monitor’s samples through the perfetto-producer writer only, flushes every 2 seconds, and restores the previous writer set afterwards. The file writers stay off because a chrometrace write allocates tens of megabytes. The flushes are Kanzi Monitor allocations, and they appear in the profile under SampleCollector. In Running app mode the tracks start with the capture, and in From launch mode with the application’s startup, because the writer leaves out samples from before the capture started. When overwatch.writers lists perfetto-producer as unavailable, as in a build without the producer SDK, the card refuses the tracks with Kanzi Monitor’s reason before it records anything; capture without them.

  • An idle application records next to nothing. In Running app mode, an application that idle suspend has stopped renders no frames and allocates almost nothing, so the profile is close to empty. Turn idle suspend off for the capture (idlesuspend 0 in the Console tab), or interact with the application while it runs.

  • Perfetto UI’s Trace Doctor reports “Heapprofd sampling interval too low” for the default sampling of 4 KB. The warning is expected: the default records more call stacks at a higher cost, which suits short captures.

  • Package defaults to the application in the foreground on the device.

Requirements: Android 10 or later, adb on the bridge host (on PATH or in the Android SDK’s platform-tools), exactly one device attached (set ANDROID_SERIAL when there are several), and an application that is profileable or debuggable unless the device runs a userdebug build. A Kanzi Profiling build is neither by default; add <profileable android:shell="true"/> inside <application> in AndroidManifest.xml. When heapprofd refuses the application, the card says so instead of returning an empty profile.

Capturing screenshots

Screenshot capture schedules a framebuffer readback for the next render frame. If the application is not rendering new frames, the capture cannot complete and the UI reports Screenshot timed out — render stage did not complete. When running under Studio Preview, enable Allow preview to update if not in focus so the preview keeps rendering while the Monitor Web UI has focus.

Serial bandwidth considerations

At 115200 baud (approximately 11.5 KB/s), large responses like texture previews or screenshots can be slow. The UI automatically reduces default image sizes on serial connections.

Recommendations:

  • Use a higher baud rate when the hardware supports it (--baud-rate 921600).

  • Text-based commands (nodes, props, perf) work well even at 115200 baud.

  • Avoid full-resolution images over serial unless necessary. The UI shows a confirmation dialog before proceeding.

  • Trace files can be several MB. The UI does not auto-fetch them over serial.

See also

Using the Overwatch service

Using the Command Processor service

Configuring Kanzi Monitor