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, textures, render passes, screen capture, 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 known Kanzi target platforms.
Some features require Kanzi 3.10 or later (version-guarded with KANZI_VERSION_UPDATE >= 10). On older Kanzi versions, these commands return an error message indicating the feature is not available.
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.
Screenshot capture uses a two-phase protocol: the first call schedules a capture for the next RenderStage callback (because commands run before rendering, leaving framebuffer 0 empty at command time). The client polls until the image is ready.
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 (includes
buildConfig, graphicsLogAvailable).
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.
Querying resources and memory¶
overwatch.resources Get all loaded resources as JSON with memory info.
overwatch.allresources [name_filter] Get all resources (created and loaded) as JSON.
Optional name filter. (Kanzi 3.10+)
overwatch.resourceinfo <index> Get detailed resource info as JSON. (Kanzi 3.10+)
overwatch.purge Purge unused resources from the ResourceManager.
Previewing textures and graphics¶
overwatch.texturepreview <index> [maxDim] [gpu] Get texture preview as base64 RGBA.
(Kanzi 3.10+)
overwatch.framebuffers Get all FBO-backed render-target textures
as JSON. (Kanzi 3.10+)
overwatch.screenshot [maxDim] [outputIndex] Capture default framebuffer (FBO 0)
as base64 RGBA.
overwatch.texturepreview returns a downscaled RGBA image of the texture at the given resource index. The optional maxDim parameter limits the longest dimension (default: 256). The optional gpu flag forces GPU readback for textures that only exist on the GPU.
overwatch.screenshot uses a two-phase capture protocol. The first call schedules the capture for the next render frame and returns {"status":"scheduled"}. The client polls with the same command until the image is ready, at which point it returns the base64-encoded RGBA data.
Inspecting render passes¶
overwatch.renderpasses Get render pass tree as JSON. (Kanzi 3.10+)
overwatch.renderpasspreview <index> [maxDim] Get CompositionTarget preview as base64 RGBA.
(Kanzi 3.10+)
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 Query log buffer configuration as JSON.
overwatch.logconfig maxentries <count> Set the log buffer size at runtime.
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).
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.
Inspecting fonts and glyph caches¶
overwatch.fonts Get all active FontRuntimes as JSON with
font identity, style definition, glyph cache
state, font metrics, and node usage.
overwatch.glyphcachepreview <index> [maxDim] Get glyph cache texture preview as base64
RGBA. The index refers to a font entry from
overwatch.fonts.
overwatch.setglyphcachesize <width> <height> Set glyph cache texture size for newly
created caches. Existing caches retain their
current size. Requires OverwatchPropertyChangeEnabled.
Font inspection requires a registered node tree. When the node tree is not available, overwatch.fonts returns "nodeTreeAvailable":false with an empty font list, and overwatch.glyphcachepreview returns an error message.
The overwatch.fonts response includes a uniqueCacheCount field and a deduplicated totalGpuMemory total. When the glyph cache size has been overridden, a configuredGlyphCacheSize object is included.
Querying graphics information¶
overwatch.graphics Get graphics and GPU information as JSON (GL vendor,
renderer, version, extensions).
Controlling graphics API call logging¶
overwatch.graphicslog Query current graphics logging state as JSON.
overwatch.graphicslog 1 Enable continuous graphics API call logging.
overwatch.graphicslog 1 dump Enable logging with GL state dump on draw calls.
overwatch.graphicslog 1 dump 5 Enable logging with dump for 5 frames, then auto-disable.
overwatch.graphicslog 0 Disable graphics logging.
When enabled, all OpenGL API calls made by the Kanzi renderer are logged to all registered loggers. The dump option adds a full GL state snapshot after every draw call, including framebuffer state, viewport, vertex attributes, shader program details, and texture bindings.
Frame-count limiting uses a RenderStage countdown — after the specified number of frames, logging is automatically disabled. Frame boundary markers (--- RenderStage entered: Frame N ---) are injected into the log stream between frames to identify per-frame GL call sequences.
The graphicslog console command provides the same functionality in a human-readable format: graphicslog [0|1] [dump].
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. Usage: |
|
Gets resource info as JSON. Usage: |
|
Gets texture preview as base64 RGBA. Usage: |
|
Gets FBO-backed textures as JSON. |
|
Captures screen as base64 RGBA. Usage: |
|
Gets render pass tree as JSON. |
|
Gets render pass preview as base64 RGBA. 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 log buffer configuration. Usage: |
|
Gets graphics information as JSON. |
|
Gets or sets graphics API call logging. Usage: |
|
Gets DataSource trees as JSON. |
|
Sets a DataObject value. Usage: |
|
Gets active FontRuntimes as JSON with style, glyph cache, metrics, and node info. |
|
Gets glyph cache texture preview as base64 RGBA. Usage: |
|
Sets glyph cache texture size for new caches. Usage: |
|
Purges unused resources. |