Getting started with Kanzi Monitor¶
After you extract the Kanzi Monitor package to <KanziWorkspace>/Engine/plugins/monitor/, the next step is to add Kanzi Monitor to your Kanzi application.
Kanzi Monitor supports two usage modes:
In a Kanzi application project — Integrate Kanzi Monitor into your project build system. This gives full access to all features and is the primary use case.
In Kanzi Studio — Import the Kanzi Monitor DLL directly in Kanzi Studio as a plugin. Some Kanzi Monitor features are not available in the Kanzi Studio Preview.
The rest of this page covers the application project path.
Integrating into your application project¶
To add Kanzi Monitor to your application project, follow the integration steps for your target platform and build system.
See Integrating Kanzi Monitor into existing projects.
When integration is complete, the plugin loads when the application starts and all services run with their default settings.
Loading Kanzi Monitor before dependent plugins¶
Kanzi can load plugins from dynamic libraries in an unpredictable order, and the plugin order baked into the kzb (from the Kanzi Studio plugin-import order) is not guaranteed. If another plugin depends on Kanzi Monitor during its own initialization, make the application load Kanzi Monitor first rather than relying on the kzb loader.
The recommended way is to add "kzmonitor" to the module names in onConfigure, so the application loads the Kanzi Monitor core before any other plugin:
configuration.moduleNames.push_back("kzmonitor");
This is the right approach for platforms where Kanzi Monitor is a dynamically-loaded module (Windows *_DLL builds and Android). On platforms where Kanzi Monitor is linked into the executable and registered with KanziMonitorModule::registerModule() (Windows static builds and Linux/SCons), do not also add it to moduleNames — on Linux that loads the library a second time and re-registers the Logging profiling category, which aborts the application. The bundled example (kanziperformancetools_main.cpp) shows this platform-aware pattern. See also Known issues.
Enabling features that depend on the Application instance¶
Some features of Kanzi Monitor require access to the Application instance. To enable these features, provide the Application instance to the Kanzi Monitor plugin from your C++ Application-derived class.
In the Application-derived class, include the Kanzi Monitor header and call the C++ API in the onConfigure(...) function:
#include <kanzimonitor_module.hpp>
KanziMonitorModule::ApplicationReference::get().setApplication(this);
Note
On Kanzi 3.6 the App Framework application is native C++ on every platform, including Android — there is no droidfw Java API. Provide the Application instance from C++ as shown above.
Driving Kanzi Monitor per-frame services¶
Two Kanzi Monitor features need to run at specific points in each frame and therefore
require a small amount of application wiring: the Performance service (frame
and render statistics) and Overwatch screenshot capture. On Kanzi 3.9 these were
driven by the engine MainLoopScheduler; Kanzi 3.6 has no MainLoopScheduler,
and a plugin cannot hook the render stages itself, so your application drives them
by forwarding two Application lifecycle hooks to Kanzi Monitor.
The Trace service does not need any wiring — it self-drives (see The Trace service needs no wiring below).
In your Application-derived class, call the Kanzi Monitor hooks from the matching
Application overrides:
void updateOverride(kanzi::chrono::milliseconds deltaTime) KZ_OVERRIDE
{
BaseClass::updateOverride(deltaTime);
if (KanziMonitorModule* monitor = getKanziMonitorModule(getDomain()))
{
kanzi::chrono::nanoseconds delta = kanzi::chrono::duration_cast<kanzi::chrono::nanoseconds>(deltaTime);
if (PerformanceService* performance = monitor->getPerformanceService())
{
performance->onFrameUpdate(delta);
}
}
}
void onPostRender() KZ_OVERRIDE
{
if (KanziMonitorModule* monitor = getKanziMonitorModule(getDomain()))
{
if (PerformanceService* performance = monitor->getPerformanceService())
{
performance->onPostRender();
}
if (OverwatchService* overwatch = monitor->getOverwatchService())
{
overwatch->onPostRender();
}
}
BaseClass::onPostRender();
}
The null checks let the same application run with Kanzi Monitor absent or disabled.
If the hooks are not forwarded, the Performance service stays inert and its
metrics read zero (Kanzi Monitor logs a one-time warning to help you diagnose the missing
wiring), and overwatch.screenshot never completes — it keeps returning a
pending status.
Note
The monitor_example application wraps its Application in an optional
template mixin (ProfiledBaseApplication) that performs this forwarding
(and adds Application-framework profiling) in one line. You can adopt the same
pattern, but the explicit calls above are the canonical contract.
The Trace service needs no wiring¶
The Trace service’s frame-duration write trigger (WritingOnFrameDurationThreshold)
does not require the wiring above. The Trace service registers its own per-frame
task with the Kanzi task scheduler, so the trigger works whether or not the
application forwards any hooks — configure the threshold in kanzimonitor.cfg
and it takes effect. (Its periodic collect/write timers are likewise self-driven.)
The Performance service, by contrast, is driven from the application hooks by
design: sampling from more than one main-loop stage — the update stage
(onFrameUpdate) and the post-render stage (onPostRender) — yields
finer-grained performance data than a single task-scheduler callback could, and the
render statistics are only valid after rendering. That is why it is worth wiring.
Enabling features that depend on the scene¶
Some features of Kanzi Monitor require access to the Kanzi node tree.
The Kanzi Monitor plugin automatically registers the node tree when loading the Startup Prefab from the kzb file.
You can configure this automatic registration using the NodeRegisteringScreenEnabled setting in kanzimonitor.cfg. The automatic registration is enabled by default.
If you disable automatic registration, or create the node tree with application code, register the root explicitly using an API call. If you register the root explicitly, also unregister the root during application shutdown.
For convenience, if there are no root nodes registered, Kanzi Monitor attempts to access the node tree from the Application, if it is available. See Enabling features that depend on the Application instance.
Registering the root node in C++¶
To register the root node in a C++ application:
In the Application-derived class, register the root node in the onProjectLoaded(...) function:
// The Monitor plugin automatically registers the Startup Prefab node tree by default.
// If the automatic registration is disabled or does not work,
// the application can register it explicitly.
// If the registration is done explicitly, unregister the tree during shutdown.
KanziMonitorModule::ApplicationReference::get().registerRoot(...);
Setting permissions¶
Android¶
Kanzi Monitor requires privileges to write files and open TCP sockets. On Android, you must add these permissions to the application manifest and grant them on the device before using Kanzi Monitor.
Serial port communication¶
Communication over serial ports is optional, and the default configuration setting is disabled. If you want to use serial communication, ensure that UART privileges are granted on the device.
See also¶
Integrating Kanzi Monitor into existing projects
Working with Kanzi Monitor services