Integrating Kanzi Monitor from source code¶
You can integrate Kanzi Monitor from source code into your Kanzi application project.
The source code is located in the <KanziWorkspace>/Engine/plugins/monitor/src directory.
To load Kanzi Monitor, the application also needs it in its Kanzi Studio project or in ModuleNames. To add it to the Kanzi Studio project, use Add Monitor Engine plugin to Studio Project in the Kanzi Monitor Tools window of Kanzi Studio. See Using the Kanzi Studio plugin.
Build options¶
Kanzi Monitor exposes two CMake options that control how it is built into your application:
Option |
Description |
|---|---|
|
Required. Enables Kanzi Monitor in your project. When off, the integration block below is skipped and no Kanzi Monitor code is built. |
|
Optional. Links the vendored Perfetto producer SDK into |
Pass both flags on the same CMake command line. They can be added to either Windows or Android integrations.
Note
The pre-built Android binaries shipped under Engine/plugins/monitor/lib/android/ are built with -DKZMONITOR_PERFETTO_PRODUCER=ON. If you use Integrating Kanzi Monitor as a prebuilt library instead of building from source, ActiveWriters = perfetto-producer and PerfettoProducerCaptureSeconds work without any extra CMake flag — the producer SDK is already linked. You can verify this in logcat: Perfetto producer SDK initialized (system + in-process backends) appears at startup.
Integrating to Windows projects with CMake and Visual Studio¶
To integrate Kanzi Monitor from source to a Windows application project:
Enable Kanzi Monitor in the top-level
CMakeLists.txt. To also enable the Perfetto producer SDK (see Build options), add-DKZMONITOR_PERFETTO_PRODUCER=ONwhere you pass-DKANZI_LINK_KZMONITOR=ON.If a Kanzi 4.1 application template created the application, its
CMakeLists.txtalready has anif(KANZI_LINK_KZMONITOR)block. Pass-DKANZI_LINK_KZMONITOR=ONwhen you generate the CMake project.Otherwise, for example when an earlier version of Kanzi Studio created the application, add this block after the
add_executable(${PROJECT_NAME} ...)call, and pass-DKANZI_LINK_KZMONITOR=ONwhen you generate the CMake project:Note
This block ends with
target_link_libraries(${PROJECT_NAME} ...), so place it after theadd_executable(${PROJECT_NAME} ...)call that creates the target, not immediately afterinclude(kanzi-common). Placing it before the target exists fails CMake configuration with “Cannot specify link libraries for target … which is not built by this project.”if(KANZI_LINK_KZMONITOR) set(PLUGIN_COMMON_SETUP cmake/common-setup.cmake) # KANZI_MONITOR_ROOT can be set explicitly: cmake -DKANZI_MONITOR_ROOT=<path> # If not set, auto-detection from known locations is attempted. if(NOT KANZI_MONITOR_ROOT) if(EXISTS ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor/${PLUGIN_COMMON_SETUP}) set(KANZI_MONITOR_ROOT ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor) elseif(DEFINED ENV{KANZI_HOME} AND EXISTS "$ENV{KANZI_HOME}/Engine/plugins/monitor/${PLUGIN_COMMON_SETUP}") set(KANZI_MONITOR_ROOT "$ENV{KANZI_HOME}/Engine/plugins/monitor") endif() if(NOT KANZI_MONITOR_ROOT) message(FATAL_ERROR "Cannot find Monitor plugin root directory. " "Pass -DKANZI_MONITOR_ROOT=<path> to CMake, set the KANZI_HOME " "environment variable to your Kanzi workspace root, or install " "the plugin under 'WORKSPACE/Engine/plugins'.") endif() endif() include(${KANZI_MONITOR_ROOT}/${PLUGIN_COMMON_SETUP}) include(${KANZI_MONITOR_ROOT}/cmake/monitor-config.cmake) target_link_libraries(${PROJECT_NAME} ${KANZI_MONITOR_NAMESPACE}kzmonitor) endif()
Inside the
if(KANZI_LINK_KZMONITOR)block, add the Kanzi Monitor library as a subdirectory to build from source:add_subdirectory(${KANZI_MONITOR_ROOT} "${CMAKE_BINARY_DIR}/monitor")
Note
When Kanzi Monitor is added as a subdirectory, its example application is not built by default. To also build the example, pass
-DBUILD_EXAMPLES=ONto CMake.Regenerate the project from the updated CMake files.
For example, run the
generate_cmake_vs2022_solution.batscript.(Optional) If the Kanzi Monitor plugin is not added to the Kanzi Studio project, add the
kzmonitormodule to module names in eitherapplication.cfgor under theonConfigurefunction:application.cfg: ModuleNames = "kzmonitor"
void onConfigure(ApplicationProperties& configuration) override { configuration.moduleNames = { "kzmonitor" }; }
(Optional) To enable rendering statistics and GPU object counts in Release and Profiling builds, enable the Kanzi graphics statistics layer. You can do this in either
application.cfg:GraphicsStatisticEnabled = true
or in
onConfigure():configuration.graphicsStatisticsEnabled = true;
In Debug builds, the graphics statistics layer is enabled by default. Without this setting, the Kanzi Monitor still reports FPS, frame time, resource counts, and memory usage, but per-frame rendering counters and GPU object counts remain zero.
See GraphicsStatisticEnabled in the Kanzi application configuration reference.
Make sure that the application has the necessary privileges to write files and open TCP sockets.
Integrating to Android projects with Gradle, CMake, and Android Studio¶
Note
On Android, you must link Kanzi Monitor with target_link_libraries at build time.
Dynamic plugin loading via ModuleNames alone does not work on Android because RTTI type information is not shared across .so library boundaries, which prevents the Kanzi Engine from recognizing the plugin module.
To integrate Kanzi Monitor from source to an Android application project:
In the
configs/platforms/android_gradle/kanzinative/build.gradle, enable Kanzi Monitor linking. If a Kanzi 4.1 application template created the application, the file has the linearguments "-DKANZI_LINK_KZMONITOR=OFF": changeOFFtoON. Otherwise add the argument, as shown below. To also enable the Perfetto producer SDK (see Build options), pass-DKZMONITOR_PERFETTO_PRODUCER=ONon the same line.Note
In Gradle projects, enable Kanzi Monitor linking by passing
-DKANZI_LINK_KZMONITOR=ONin thecmake { arguments }block of thekanzinative/build.gradle:cmake { // Enable to add Monitor plugin to the AAR. arguments "-DKANZI_LINK_KZMONITOR=ON" }
In the
CMakeLists.txtof the application:If a Kanzi 4.1 application template created the application, the file already has an
if(KANZI_LINK_KZMONITOR)block. Go to the next step.Otherwise, add this block after the
add_executable(${PROJECT_NAME} ...)call:Note
This block ends with
target_link_libraries(${PROJECT_NAME} ...), so place it after theadd_executable(${PROJECT_NAME} ...)call that creates the target, not immediately afterinclude(kanzi-common). Placing it before the target exists fails CMake configuration with “Cannot specify link libraries for target … which is not built by this project.”if(KANZI_LINK_KZMONITOR) set(PLUGIN_COMMON_SETUP cmake/common-setup.cmake) # KANZI_MONITOR_ROOT can be set explicitly: cmake -DKANZI_MONITOR_ROOT=<path> # If not set, auto-detection from known locations is attempted. if(NOT KANZI_MONITOR_ROOT) if(EXISTS ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor/${PLUGIN_COMMON_SETUP}) set(KANZI_MONITOR_ROOT ${PROJECT_SOURCE_DIR}/../../../Engine/plugins/monitor) elseif(DEFINED ENV{KANZI_HOME} AND EXISTS "$ENV{KANZI_HOME}/Engine/plugins/monitor/${PLUGIN_COMMON_SETUP}") set(KANZI_MONITOR_ROOT "$ENV{KANZI_HOME}/Engine/plugins/monitor") endif() if(NOT KANZI_MONITOR_ROOT) message(FATAL_ERROR "Cannot find Monitor plugin root directory. " "Pass -DKANZI_MONITOR_ROOT=<path> to CMake, set the KANZI_HOME " "environment variable to your Kanzi workspace root, or install " "the plugin under 'WORKSPACE/Engine/plugins'.") endif() endif() include(${KANZI_MONITOR_ROOT}/${PLUGIN_COMMON_SETUP}) include(${KANZI_MONITOR_ROOT}/cmake/monitor-config.cmake) target_link_libraries(${PROJECT_NAME} ${KANZI_MONITOR_NAMESPACE}kzmonitor) endif()
Inside the
if(KANZI_LINK_KZMONITOR)block, add the Kanzi Monitor library as a subdirectory to build from source:add_subdirectory(${KANZI_MONITOR_ROOT} "${CMAKE_BINARY_DIR}/monitor")
If the Kanzi Monitor plugin is not added to the Kanzi Studio project, enable the plugin by adding it to the
ModuleNamesconfiguration option inapplication.cfg:ModuleNames = "kzmonitor"
This is the recommended registration method for Android because it works with both Kanzi application frameworks:
appfw (Basic Application template) – The application has a C++
ExampleApplicationsubclass, so you can alternatively setconfiguration.moduleNames = { "kzmonitor" };inonConfigure().droidfw (Android Application template) – The application lifecycle is Java-driven and the C++ source is a stub, so
application.cfgis the only viable registration path.
(Optional) To enable rendering statistics and GPU object counts in Release and Profiling builds, enable the Kanzi graphics statistics layer. You can do this in
application.cfg:GraphicsStatisticEnabled = true
or in
onConfigure()(appfw projects only):configuration.graphicsStatisticsEnabled = true;
In Debug builds, the graphics statistics layer is enabled by default. Without this setting, the Kanzi Monitor still reports FPS, frame time, resource counts, and memory usage, but per-frame rendering counters and GPU object counts remain zero.
See GraphicsStatisticEnabled in the Kanzi application configuration reference.
Regenerate the project from the updated CMake files.
For example, update your Android Studio and Gradle environment with the changes that you made to the CMake files.
Make sure that the application has the necessary privileges to write files and open TCP sockets. See Setting permissions on Android.