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.
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
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.
overwatch.resourceinfo <index> Get detailed resource info as JSON.
overwatch.purge Purge unused resources from the ResourceManager.
Previewing textures and graphics¶
overwatch.texturepreview <index> [maxDim] [gpu] Get texture preview as base64 RGBA.
overwatch.framebuffers Get all FBO-backed render-target textures
as JSON.
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.
All image commands (overwatch.texturepreview, overwatch.screenshot, overwatch.renderpasspreview) return raw RGBA data. The image is vertically flipped relative to screen orientation because GPU framebuffer readback data is bottom-up. Flip the image vertically before display.
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.
overwatch.renderpasspreview <index> [maxDim] Get CompositionTarget preview as base64 RGBA.
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.
overwatch.perf returns per-frame rendering statistics using Kanzi 4.0 metric names (drawCount, drawnElements, imageCount, framebufferCount, renderPipelineCount, constantDataCount, renderPassCount, renderPipelineBindCount, computeDispatchCount). For backward compatibility, the old metric names (batchCount, triangleCount, textureSwitches, framebufferSwitches, shaderSwitches, uniformsSent) are also included with the same values.
The response also includes a gpuObjects array with all 16 GPU object types (current, maximum, lifetime, increase, decrease counts) and a stagingBuffers array with per-buffer memory usage.
Note
Rendering statistics and GPU object counts require the Kanzi graphics statistics layer.
In Debug builds this is enabled by default; in Release and Profiling builds, set
GraphicsStatisticEnabled = true in application.cfg or
configuration.graphicsStatisticsEnabled = true in onConfigure().
See Built-in metrics for details.
Performance watchers integrate with the Performance service. See Using performance watchers.
Capturing traces and logs¶
overwatch.trace Capture a Monitor profiling trace and write to file.
overwatch.fetchtrace Fetch the most recently captured Monitor trace as JSON.
overwatch.kztrace Capture a kzTrace snapshot (engine-native tracing).
overwatch.fetchkztrace Fetch the most recently captured kzTrace as JSON.
overwatch.logs Get recent log entries as JSON with timestamp, level,
category, and message.
Kanzi Monitor supports two trace sources that both produce Chrome Trace JSON compatible with Perfetto:
Monitor profiling trace (
overwatch.trace/overwatch.fetchtrace) – Collects profiling data through the Monitor Trace service. In all build configurations the trace includes default registry profilers, named interval profilers, and custom collection tasks such as PerformanceInfo counters. In Profiling builds the trace additionally includes Kanzi Engine engine-internal instrumentation: main loop and startup timing, domain node/layout/render operations, and resource loading. RequiresServiceTraceEnabled = 1. See Using the Profiling Trace service for details.kzTrace (
overwatch.kztrace/overwatch.fetchkztrace) – Captures a snapshot from the Kanzi Engine tracing subsystem (kzTracescope macros). Covers engine-internal instrumentation such as frame stages, rendering, resource loading, and node operations. Available only in Debug and Profiling builds (KANZI_TRACING_BUILD). In Release builds,overwatch.kztracereturns an error with a hint about the required build configuration. See the Tracing API reference and Tracing application configuration in the Kanzi Engine documentation.
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.fetchkztrace works the same way for kzTrace files.
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 (backend,
device, API version, driver version, features).
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 Monitor profiling trace and writes to file. |
|
Fetches the last Monitor profiling trace as JSON. |
|
Captures a kzTrace snapshot (engine-native tracing, requires Debug or Profiling build). |
|
Fetches the last kzTrace as JSON. |
|
Gets recent log entries as JSON. |
|
Gets graphics information as JSON. |
|
Gets DataSource trees as JSON. |
|
Sets a DataObject value. Usage: |
|
Purges unused resources. |