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 = 0 in kanzimonitor.cfg.
Property editing is enabled by default. To disable it, set OverwatchPropertyChangeEnabled = 0 in kanzimonitor.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).

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. For textures,
                                       textureInfo includes type, faceCount, sliceCount,
                                       and isCubemap.
overwatch.purge                        Purge unused resources from the ResourceManager.

Previewing textures and graphics¶

overwatch.texturepreview <index> [maxDim] [gpu] [face=<n>]
                                                   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. The optional face=<n> argument selects a single cubemap face, where n is 0–5 in the order +X, -X, +Y, -Y, +Z, -Z (default: 0). The response includes face and faceCount fields.

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(s). The format(s) depend on which writers
                                   are active — chrometrace produces .json, perfetto
                                   produces .perfetto-trace.
overwatch.fetchtrace               Fetch the most recently captured chrometrace
                                   (.json) trace as a JSON string. Returns an error
                                   pointing at fetchperfettotrace if only the
                                   perfetto writer is active.
overwatch.fetchperfettotrace       Fetch the most recently captured .perfetto-trace
                                   (native Perfetto protobuf). The binary is
                                   base64-encoded inside a JSON envelope so it can
                                   be transported over the line-delimited protocol.
overwatch.kztrace                  Capture a kzTrace snapshot (engine-native tracing).
overwatch.fetchkztrace             Fetch the most recently captured kzTrace as JSON.
overwatch.writers                  List registered trace writers as JSON.
overwatch.activatewriter <name>    Activate a trace writer by name.
overwatch.deactivatewriter <name>  Deactivate a trace writer by name.
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.

Kanzi Monitor supports two trace sources:

Monitor profiling trace (overwatch.trace / overwatch.fetchtrace) – Collects profiling data through the Monitor Trace service. The output format is determined by which writers are active in ActiveWriters (see Configuring Kanzi Monitor): chrometrace produces Chrome Trace Format JSON (.json), perfetto produces native Perfetto protobuf (.perfetto-trace), or both can be active simultaneously. 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. Requires ServiceTraceEnabled = 1. See Using the Profiling Trace service for details.
kzTrace (overwatch.kztrace / overwatch.fetchkztrace) – Captures a snapshot from the Kanzi Engine tracing subsystem (kzTrace scope macros). Always produces Chrome Trace Format JSON. 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.kztrace returns an error with a hint about the required build configuration. See the Tracing API reference and Tracing application configuration in the Kanzi Engine documentation.

Both outputs are compatible with Perfetto UI: drag a .json or .perfetto-trace file into the page to view it.

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). It only returns .json (chrometrace) output — when only the perfetto writer is active it returns an error pointing at overwatch.fetchperfettotrace. That command reads the most recent .perfetto-trace file (binary protobuf), base64-encodes the bytes, and emits a JSON envelope of the form {"file":"<name>.perfetto-trace","size":<bytes>,"data":"<base64>"}; the Web UI and MCP server decode the base64 on receipt. overwatch.fetchkztrace works the same way as fetchtrace for kzTrace files.

The trace writers are themselves inspectable and controllable at runtime through three additional commands — overwatch.writers (lists all registered writers with name, description, and active state as JSON), overwatch.activatewriter <name>, and overwatch.deactivatewriter <name>. See Using the Profiling Trace service for the registry model and built-in writer reference.

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 (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
`overwatch`	Shows Overwatch service status.
`overwatch.status`	Gets Overwatch service status as JSON.
`overwatch.nodes`	Gets node tree as JSON. Usage: `overwatch.nodes [maxDepth]`
`overwatch.props`	Gets properties of a node as JSON. Usage: `overwatch.props <node_path>`
`overwatch.setprop`	Sets a property value. Usage: `overwatch.setprop <path> <property> <value>`
`overwatch.resources`	Gets loaded resources as JSON.
`overwatch.allresources`	Gets all resources as JSON. Usage: `overwatch.allresources [name_filter]`
`overwatch.resourceinfo`	Gets resource info as JSON. Usage: `overwatch.resourceinfo <index>`. For textures, the `textureInfo` block includes `type`, `faceCount`, `sliceCount`, and `isCubemap`.
`overwatch.texturepreview`	Gets texture preview as base64 RGBA. Usage: `overwatch.texturepreview <index> [maxDim] [gpu] [face=<n>]`. `face=<n>` (0–5) selects a cubemap face.
`overwatch.framebuffers`	Gets FBO-backed textures as JSON.
`overwatch.screenshot`	Captures screen as base64 RGBA. Usage: `overwatch.screenshot [maxDim] [outputIndex]`
`overwatch.renderpasses`	Gets render pass tree as JSON.
`overwatch.renderpasspreview`	Gets render pass preview as base64 RGBA. Usage: `overwatch.renderpasspreview <index> [maxDim]`
`overwatch.perf`	Gets performance metrics as JSON.
`overwatch.watchers`	Gets watchers and metrics as JSON.
`overwatch.addwatcher`	Adds a performance watcher. Usage: `overwatch.addwatcher <metric> <below\|above> <threshold> <command> [args]`
`overwatch.removewatcher`	Removes a watcher. Usage: `overwatch.removewatcher <id>`
`overwatch.resetwatcher`	Resets a triggered watcher. Usage: `overwatch.resetwatcher <id>`
`overwatch.clearwatchers`	Removes all watchers.
`overwatch.trace`	Captures a Monitor profiling trace and writes a file per active writer (`.json` for `chrometrace`, `.perfetto-trace` for `perfetto`).
`overwatch.fetchtrace`	Fetches the last Monitor profiling `.json` (chrometrace) trace as a JSON string. Returns an error pointing at `fetchperfettotrace` if only the perfetto writer ran.
`overwatch.fetchperfettotrace`	Fetches the last Monitor profiling `.perfetto-trace` file as `{file, size, data}` JSON envelope with the binary base64-encoded.
`overwatch.kztrace`	Captures a kzTrace snapshot (engine-native tracing, requires Debug or Profiling build).
`overwatch.fetchkztrace`	Fetches the last kzTrace as JSON.
`overwatch.writers`	Lists registered trace writers as JSON with `name`, `description`, and `active` state.
`overwatch.activatewriter`	Activates a trace writer by name. Usage: `overwatch.activatewriter <name>`
`overwatch.deactivatewriter`	Deactivates a trace writer by name. Usage: `overwatch.deactivatewriter <name>`
`overwatch.logs`	Gets recent log entries as JSON.
`overwatch.logconfig`	Gets or sets log buffer configuration. Usage: `overwatch.logconfig [maxentries <count>]`
`overwatch.graphics`	Gets graphics information as JSON.
`overwatch.datasources`	Gets DataSource trees as JSON.
`overwatch.setdata`	Sets a DataObject value. Usage: `overwatch.setdata <datasource> <path> <value>`
`overwatch.fonts`	Gets active FontRuntimes as JSON with style, glyph cache, metrics, and node info.
`overwatch.glyphcachepreview`	Gets glyph cache texture preview as base64 RGBA. Usage: `overwatch.glyphcachepreview <index> [maxDim]`
`overwatch.setglyphcachesize`	Sets glyph cache texture size for new caches. Usage: `overwatch.setglyphcachesize <width> <height>`
`overwatch.purge`	Purges unused resources.