Using the Overwatch service¶
The Overwatch service provides JSON-based remote introspection of a running Kanzi application.
It exposes the scene graph, node properties, resources, performance metrics, data sources, logs, and trace capture through a set of overwatch.* commands.
You can use these commands from the local console, the remote TCP console, or the serial console. They are also the foundation for the Monitor Web UI, which provides a browser-based interface for visual debugging.
Platform support¶
The Overwatch service builds from sources on all Kanzi target platforms supported by this release.
Note
All overwatch.* commands are registered on Kanzi 3.6 in this release. The
texture and render-pass previews read persistent render-target textures
through the GPU-readback path (a temporary framebuffer object) and capture
synchronously; only overwatch.screenshot (the default framebuffer) depends
on the application driving the per-frame contract (see Capturing a screenshot).
The resource-enumeration commands (overwatch.allresources,
overwatch.resourceinfo, overwatch.framebuffers) are available: on
Kanzi 3.6 they enumerate the loaded resources through getAllLoadedResources()
and use each resource’s position in that listing as its index. Because that
listing contains only loaded resources — the Kanzi Engine cannot enumerate
registered-but-unloaded resources on 3.6 — overwatch.allresources returns
the same set as overwatch.resources.
A resource index is a short-lived handle, not a durable identifier. The
resource-manager state can change at any time, so an index can become
out of range or shift to a different resource between commands. Treat an index
as information with a short shelf-life: fetch a listing and pass its indices to
overwatch.resourceinfo promptly, within the same application state. This is
inherent to the resource listing rather than specific to Kanzi 3.6 — the newer
ResourceManager::getAllResources() enumeration is documented to be likely
invalid after any iteration of the main loop.
How the Overwatch service works¶
The Overwatch service registers overwatch.* commands with the Command Processor service.
Each command queries the Kanzi Engine and returns a single-line JSON response through the standard console protocol.
Property modification (overwatch.setprop) and data modification (overwatch.setdata) are enabled by default. To disable them and operate in read-only mode, set OverwatchPropertyChangeEnabled = 0 in the configuration file.
Setting up the Overwatch service¶
The Overwatch service is enabled by default. To disable it, set
ServiceOverwatchEnabled = 0inkanzimonitor.cfg.Property editing is enabled by default. To disable it, set
OverwatchPropertyChangeEnabled = 0inkanzimonitor.cfg.Start the application and connect using the remote console, local console, or Monitor Web UI.
Send
overwatch.*commands and receive JSON responses.
Querying service status¶
overwatch Show Overwatch service status
overwatch.status Get Overwatch service status as JSON
overwatch.status reports whether the service is enabled and initialized, the Kanzi Monitor version, the buildConfig (Debug, Profiling, or Release, from the Kanzi compile-time defines), and graphicsLogAvailable (whether overwatch.graphicslog is supported on this build).
Working with the node tree and properties¶
overwatch.nodes [maxDepth] Get node tree as JSON. Optional depth limit.
overwatch.props <node_path> Get properties of a node as JSON.
overwatch.setprop <path> <property> <value> Set a property value on a node.
The node path uses / separators matching the Kanzi node hierarchy (for example, Viewport 2D/Scene/Text Block 3D). You can quote paths and values that contain spaces.
overwatch.setprop requires OverwatchPropertyChangeEnabled = 1.
Note
On Kanzi 3.6, overwatch.props lists a node’s locally-set property values
– the properties that have a local value on the node instance – with their
types and values. Kanzi 3.9 iterates the instance’s property storage directly;
that iteration (beginPropertyStorage) is not accessible on 3.6, so Monitor
instead walks the node’s metaclass property types – including those inherited
from base classes and those supplied by concept mixins (such as the Text
property on a text block) – and reports those for which hasLocalValue is
set. The result is the same set in
practice; the only case not covered is a locally-set property that is not
declared in any of the node’s metaclasses (a purely dynamic / attached property),
which 3.9 would still list. Binding-source information is not included –
the engine APIs that expose it (getBindingRuntime*) were added in Kanzi 3.9.
Common types (bool, int, float, string, color, vector) show values; other types
(SRT, matrix) are listed without a value.
Querying resources and memory¶
overwatch.resources Get all loaded resources as JSON with memory info.
overwatch.allresources ["nameFilter"] Get all resources as JSON with memory info and totals.
overwatch.resourceinfo <index> Get detailed metadata for a resource by index.
overwatch.framebuffers Get all FBO-backed textures (render targets) as JSON.
overwatch.purge Purge unused resources from the ResourceManager.
overwatch.resources lists the currently loaded resources with their CPU and GPU memory usage.
overwatch.allresources returns the same resources together with per-listing totals (totalCpuBytes, totalGpuBytes, totalUnfiltered) and accepts an optional substring nameFilter applied to resource names. Each entry carries an index — its position in the resource listing — which you pass to overwatch.resourceinfo. This index is a short-lived handle: the resource-manager state can change between commands, so consume it promptly within the same application state (see Platform support).
overwatch.resourceinfo <index> returns detailed metadata for a single resource: its name, type, URL, and CPU/GPU memory usage. When the resource is a texture, it also reports a textureInfo block with the dimensions, format (the Kanzi GraphicsFormat), mipmap level count, the texture type with its faceCount / sliceCount and an isCubemap flag (a cubemap has six faces), and whether the texture has a host-side CPU copy (hasCpuData) or is backed by a framebuffer object (hasFbo). An out-of-range index returns an error with the current resource total.
overwatch.framebuffers lists the textures that are backed by a framebuffer object (render targets), each with its dimensions, format, native FBO handle, and CPU-copy availability.
Previewing textures and render passes¶
overwatch.texturepreview <index> [maxDim] [gpu] [face=<n>] Get a base64 RGBA texture preview.
overwatch.renderpasses Get the render-pass tree as JSON.
overwatch.renderpasspreview <index> [maxDim] Preview a composition-target output.
overwatch.texturepreview returns a base64-encoded RGBA preview of the texture at index (from the resource listing), with the output and original dimensions. It uses the texture’s host-side copy when one exists; when the texture is GPU-only, pass the gpu flag to read it back from the GPU (through its framebuffer object, or a temporary one bound to the texture). maxDim downsamples the longest edge (0 = full resolution, default 256). For a cubemap, face=<n> selects which of the six faces (0–5) to preview; on Kanzi 3.6 an individual cubemap face is always read back from the GPU (the host-side per-face image is not available), so the face preview is produced the same way as the gpu path.
overwatch.renderpasses returns the render-pass tree: each node reports its name, type, resource index, and child render passes. A CompositionTargetRenderPass node additionally reports its composition-target texture (dimensions, format, FBO handle, and the texture’s resource index).
overwatch.renderpasspreview resolves the composition-target texture of a CompositionTargetRenderPass (at the given render-pass index) and returns a GPU-readback preview of it, in the same format as overwatch.texturepreview. It reaches the texture directly through the render pass, so it also works for auto-generated composition targets that are not in the resource listing (their index is reported as -1).
Note
Pixel data read back from the GPU – overwatch.texturepreview (with the
gpu flag), overwatch.renderpasspreview, overwatch.glyphcachepreview,
and overwatch.screenshot – is in GL bottom-up row order at the protocol
level, so it appears vertically flipped when drawn directly. The Monitor Web UI
and the MCP image tools reorient these previews to match the on-screen
orientation by default; in the Web UI the Flip vertical toggle switches
back to the raw bottom-up order.
Inspecting fonts and glyph caches¶
overwatch.fonts List the glyph caches in use as JSON.
overwatch.glyphcachepreview <index> [maxDim] Preview a glyph cache atlas texture.
overwatch.setglyphcachesize <width> <height> Set the glyph cache texture size.
overwatch.fonts walks the node tree for text-rendering nodes, looks each node’s (font, font size) up in the engine text manager, and returns the unique glyph cache atlases (caches), each with its fontSize, atlas texture size, CPU/GPU memory, and the nodes that share it, plus totalCpuBytes/totalGpuBytes. The command is named fonts for contract parity with Kanzi Monitor on newer Kanzi versions (where it enumerates FontRuntime objects); Kanzi 3.6 has no FontRuntime/GlyphCacheManager, so the payload is a glyph-cache-centric reduced set (no per-font style definition or cache generation counter).
overwatch.glyphcachepreview returns a base64-encoded RGBA preview of the glyph cache atlas texture at the given index (from the overwatch.fonts listing), in the same format as overwatch.texturepreview.
overwatch.setglyphcachesize sets the glyph cache texture size for newly created caches (existing caches are cleared so they are re-created at the new size on next use). Requires OverwatchPropertyChangeEnabled=1. A size below 128×128 is rejected with a warning, since text rendering may fail with too small an atlas.
Monitoring performance¶
overwatch.perf Get performance metrics as JSON.
overwatch.watchers Get performance watchers and
available metrics as JSON.
overwatch.addwatcher <metric> <below|above> <threshold> <cmd> Add a performance watcher.
overwatch.removewatcher <id> Remove a performance watcher
by ID.
overwatch.resetwatcher <id> Reset a triggered watcher back
to active.
overwatch.clearwatchers Remove all performance watchers.
Performance watchers integrate with the Performance service. See Using performance watchers.
Capturing traces and logs¶
overwatch.trace Capture a new trace and write to file.
overwatch.fetchtrace Fetch the most recently captured trace file as JSON.
overwatch.logs Get recent log entries as JSON with timestamp, level,
category, and message.
overwatch.logconfig Get or set the log buffer configuration.
Usage: overwatch.logconfig [maxentries <count>]
overwatch.graphicslog Enable or disable graphics API call logging.
Usage: overwatch.graphicslog [0|1] [dump] [frames]
overwatch.fetchtrace reads the last trace file written by the Trace service and returns its full contents as a JSON string. This can be a large response (several MB).
overwatch.logconfig with no arguments returns the current maxEntries and count as JSON. overwatch.logconfig maxentries <count> sets the log buffer size at runtime and trims the buffer immediately if it exceeds the new limit. Requires the Log service (ServiceLogEnabled=1).
overwatch.graphicslog [0|1] [dump] [frames] toggles logging of OpenGL API calls (returned as JSON: logging, dumpStateOnDrawCalls, framesRemaining). With no arguments it returns the current state. dump additionally emits the full GL state on each draw call. frames auto-disables logging after that many rendered frames. Graphics logging produces high-volume output — raise the log buffer first with overwatch.logconfig. On Kanzi 3.6 the on/off toggle works whenever the application is rendering; the frames limit and the --- Frame N --- boundary markers additionally require the application to drive the per-frame service contract (as for screenshots). The dump output relies on the OpenGL debug layer being configured for the CHROMIUM vendor, which Kanzi Monitor does automatically.
Note
Graphics-log entries are produced only while the application renders frames —
enabling logging does not by itself trigger a frame. If the application suspends
rendering while idle, no new GL-call entries appear until it renders again, so a
one-shot fetch (overwatch.logs, or the Monitor Web UI Refresh button on
the Logs tab) taken during an idle period may show nothing new. To capture output,
interact with the application (or otherwise keep it rendering, for example by
disabling idle rendering suspension), and use the Web UI Live option on the
Logs tab to sample the log continuously. Because GL logging is high-volume and the
log buffer holds a fixed number of entries, live sampling (or exporting the log)
captures more than an occasional manual refresh.
Working with data sources¶
overwatch.datasources Get all DataSources and their DataObject
trees as JSON.
overwatch.setdata <datasource> <path> <value> Set a DataObject value.
overwatch.datasources serializes DataObjectList nodes with a type of list, an itemCount field, and an items array containing each list item’s data.
Use the #index path syntax to address items inside a DataObjectList. For example, to set the name of the first contact in a list:
overwatch.setdata MyDataSource Root/contacts/#0/name "Alice"
overwatch.setdata requires OverwatchPropertyChangeEnabled = 1.
Querying graphics information¶
overwatch.graphics Get graphics and GPU information as JSON (GL vendor,
renderer, version, extensions).
Capturing a screenshot¶
overwatch.screenshot [maxDim] [outputIndex] Capture the default framebuffer
as base64-encoded RGBA.
overwatch.screenshot captures the default framebuffer (FBO 0) and returns a JSON object with the image dimensions and base64-encoded RGBA pixel data. maxDim downsamples the longest edge (0 = full resolution, default 256); outputIndex selects the graphics output on multi-display setups. The pixel data is in GL bottom-up order at the protocol level; the Monitor Web UI and MCP image tools reorient it to the on-screen orientation by default (the Web UI Flip vertical toggle switches back to raw).
The command uses a two-phase protocol. The first call returns {"status":"pending"} and schedules the capture; issue the command again to poll until the image JSON is returned. This is because the capture must run at a controlled point in the frame — after the scene is drawn but before the buffers are swapped — which Kanzi 3.6 provides through the per-frame service contract rather than the MainLoopScheduler render-stage callback used on Kanzi 3.9. The Monitor Web UI and the take_screenshot MCP tool implement the polling for you.
Note
The deferred capture runs in OverwatchService::onPostRender(), which the application must drive — the same per-frame hook that feeds the Performance service (see Getting started with Kanzi Monitor). If the application does not forward onPostRender() to Kanzi Monitor, the capture never completes and overwatch.screenshot keeps returning {"status":"pending"}. The example ProfiledBaseApplication wires this up.
When capturing in Kanzi Studio Preview, also enable Allow preview to update if not in focus — otherwise the render stage does not advance while the Preview window is unfocused, so onPostRender() never fires and the capture stays pending. The Monitor Web UI screenshot-timeout message points this out.
Understanding the JSON response format¶
All overwatch.* commands return a single line of compact JSON. The console protocol uses empty lines as message delimiters, so responses do not contain newlines.
Example request and response over the remote console:
overwatch.perf
{"fps":60.0,"appFps":60.0,"frameTime":16.6,"animTime":0.5,"batches":42,"triangles":15234,...}
Available commands¶
Command |
Description |
|---|---|
|
Shows Overwatch service status. |
|
Gets Overwatch service status as JSON. |
|
Gets node tree as JSON. Usage: |
|
Gets properties of a node as JSON. Usage: |
|
Sets a property value. Usage: |
|
Gets loaded resources as JSON. |
|
Gets all resources as JSON with totals. Usage: |
|
Gets detailed metadata for a resource. Usage: |
|
Gets FBO-backed textures (render targets) as JSON. |
|
Gets a base64 RGBA texture preview. Usage: |
|
Gets the render-pass tree as JSON. |
|
Previews a CompositionTargetRenderPass output. Usage: |
|
Lists the glyph caches in use as JSON. |
|
Previews a glyph cache atlas texture. Usage: |
|
Sets the glyph cache texture size (new caches only). Usage: |
|
Gets performance metrics as JSON. |
|
Gets watchers and metrics as JSON. |
|
Adds a performance watcher. Usage: |
|
Removes a watcher. Usage: |
|
Resets a triggered watcher. Usage: |
|
Removes all watchers. |
|
Captures a trace and writes to file. |
|
Fetches the last trace file as JSON. |
|
Gets recent log entries as JSON. |
|
Gets or sets the log buffer size. Usage: |
|
Enables/disables graphics API call logging. Usage: |
|
Gets graphics information as JSON. |
|
Captures the default framebuffer as base64 RGBA. Usage: |
|
Gets DataSource trees as JSON. |
|
Sets a DataObject value. Usage: |
|
Purges unused resources. |