Working with Kanzi Monitor services¶

Kanzi Monitor is a plugin that runs inside your Kanzi application. Its work is split into services: each service addresses one task, runs in the application’s process, and can be enabled or disabled independently in the Kanzi Monitor configuration file.

The tools that connect to a running application from outside, the console clients, the Monitor Web UI and the MCP server, are described in Working with Kanzi Monitor tools.

How the services fit together¶

The services differ in what they do to the application. Each step down this list has a larger effect on the running application, so each one has its own configuration key:

Observe: read and record anything, and change nothing. The Overwatch service reports, and the diagnostic services record.
Change values: set property values and data, and dispatch messages. The Overwatch service does this behind OverwatchPropertyChangeEnabled.
Change structure: create, move, detach and destroy nodes, and add node components. The NodeTree service.
Create content: make resources that the kzb does not contain. The Resource service.

Service	Configuration key	Commands	Level
Command Processor	`ServiceCommandProcessorEnabled`	The consoles, and the core commands such as `help`, `purge` and `nodetreeinfo`	Carries every service’s commands
Overwatch	`ServiceOverwatchEnabled`, and `OverwatchPropertyChangeEnabled` for its writes	`overwatch.*`	Observe, change values
Performance	`ServicePerformanceEnabled`	`perfinfo2`, `watch`, and the `overwatch.watcher` commands	Observe
Profiling Trace	`ServiceTraceEnabled`	`trace`, and `overwatch.trace`, `overwatch.writers`, `overwatch.profilingcategories` and the other trace commands	Observe
Log	`ServiceLogEnabled`	`loginfo`, `logdiag`, `overwatch.logs` and `overwatch.logconfig`	Observe
UI	`ServiceUIEnabled`	`ui`, `basicui`, `fontscale`	Observe
Capture	`ServiceCaptureEnabled`	`capture.*`	Observe
Debug	`ServiceDebugEnabled`	`debug.*`	Observe; a breakpoint can stop the application or run a command
NodeTree	`ServiceNodeTreeEnabled`	`nodetree.*`	Change structure
Resource	`ServiceResourceEnabled`	`resource.*`	Create content

Every service that names a node or a resource uses the same handles. A handle such as @48213977 names one object, whichever service gave it out, so a node that nodetree.create returns can be inspected with overwatch.props and a resource that resource.create returns appears in overwatch.allresources under the same handle.

Where a command lives¶

overwatch.* is where the reporting commands are, for the Overwatch service and for the diagnostic services: the trace, log and watcher commands are overwatch.* commands, next to the services’ own console commands.
A service that changes the application’s structure or creates content has its own command prefix and its own configuration key, so that you can switch it off and keep everything else. That is why the NodeTree service has nodetree.* and the Resource service has resource.*.
overwatch.dispatchmessage runs application logic, which can do more than one property write. It is still a change of values, not of structure, so it is behind OverwatchPropertyChangeEnabled with overwatch.setprop, and every dispatch is written to the application log. See Dispatching a message.
Resources have commands in two places, divided by whose resources they are. resource.* creates, holds and destroys the resources that Kanzi Monitor creates. The overwatch.* resource commands work on the application’s own resource manager and the resources it loads: overwatch.acquireresource and overwatch.unregisterresource load and let go of a resource by URL, and overwatch.setmemorystrategy and overwatch.resourcedirectory change the resource manager’s settings. See Forcing a resource into existence, and letting go of one.

NodeTree and node tree¶

The words have two meanings in Kanzi Monitor:

The NodeTree service, with its nodetree.* commands, changes the structure of the application’s nodes.
A node tree is one of the application’s Screen nodes with the nodes below it. An application with several views, such as a service-hosted application, has several. nodetreeinfo lists them, and the optional nodetree argument of ui selects one by its index.

Profiling Trace Service¶

Collects runtime profiling data from the Kanzi Engine and writes it to a JSON trace file compatible with the Perfetto trace viewer. Use this service to analyze frame timing, rendering stages, and engine operations.

See Using the Profiling Trace service

Command Processor Service¶

Provides a command-line interface for interacting with the Kanzi Engine at runtime. You can send commands through a local terminal, a remote TCP connection, or a serial port (UART).

See Using the Command Processor service, and Console protocol v1 for the wire contract if you are writing a client.

UI Service¶

Renders graphical overlays on top of the regular Kanzi application content to display runtime information and help identify rendering issues. Other services, such as the Log service, can also register their own overlay screens.

See Using the UI service

Log Service¶

Captures Kanzi Engine log messages into an in-memory ring buffer. You can view log entries through the console, on-screen overlay, or as part of a profiling trace.

See Using the Log service

Performance Service¶

Continuously measures runtime performance metrics such as frame rate, frame timing, and rendering statistics. These metrics are exported as counter tracks in the Perfetto trace viewer.

See Using the Performance service

Overwatch Service¶

Provides JSON-based remote introspection of a running Kanzi application. Exposes the scene graph, node properties, resources, textures, performance metrics, and more through a set of overwatch.* commands.

See Using the Overwatch service

Capture Service¶

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 the frames that led up to it. Frames are fetched afterwards with per-frame metadata, and the service reports what the recording costs in framerate.

See Using the Capture service

Debug Service¶

Break, log, capture a screenshot, or run a console command when a node property reaches a value. The condition is evaluated 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.

See Using the Debug service

NodeTree Service¶

Changes the structure of the running application’s node tree: create a node by metaclass or from a prefab, any number of times, anywhere in the tree; destroy, detach, reattach and move any node; and add node components. Builds test scenes the project does not contain.

See Using the NodeTree service

Resource Service¶

Creates resources in the running application, keeps them alive and destroys them: any concrete resource class, set up with property values and registered under a URL, and font families with faces and fallbacks. With the NodeTree service, it builds content the kzb does not contain.

See Using the Resource service