Metrics with Zephyr
Enable metric collection on devices running Zephyr RTOS and analyze ingested metrics in Spotflow dashboards.
This guide explains how to gather metrics from devices running Zephyr RTOS using the Spotflow device module.
Prerequisites
Before you start integrating your device with Spotflow, make sure you:
- have development environment with Zephyr 3.7, 4.1, 4.2, or 4.3,
- have established a connection to the internet from the device.
When creating a new west workspace, make sure to use a supported Zephyr version, for example, using west init --mr v4.3.0.
By default, west init checks out the main branch, which may contain changes breaking the build.
Alternatively, you can follow the Quickstart: Zephyr Integration Guide to integrate Spotflow using sample application, instead of adding the spotflow module to an existing project.
Before you start integrating your device with Spotflow, make sure you:
- have development environment with nRF Connect SDK v3.0.0 or later (v3.2.2 recommended),
- have established a connection to the internet from the device.
Alternatively, you can follow the Nordic nRF Connect SDK Integration Guide to integrate Spotflow using sample application, instead of adding the spotflow module to an existing project.
Install Spotflow Device Module
Add the spotflow module as a west dependency to your west.yml file.
manifest:
projects:
- name: spotflow
revision: main
path: modules/lib/spotflow
url: https://github.com/spotflow-io/device-sdkThen, install the west dependencies using the following command:
west updateEnable metrics in Kconfig
Add the following options to your prj.conf:
CONFIG_SPOTFLOW=y # Enable Spotflow Module
CONFIG_SPOTFLOW_DEVICE_ID="zephyr-device-001" # Set unique identifier of your device
CONFIG_SPOTFLOW_INGEST_KEY="{your-ingest-key}" # Set your Spotflow ingest key
# Enable Spotflow metrics collection
CONFIG_SPOTFLOW_METRICS=yEnable system metrics auto-collection
To collect system telemetry automatically, enable:
CONFIG_SPOTFLOW_METRICS_SYSTEM=yThe following system metrics are collected:
| Metric | How it is collected |
|---|---|
Heap Free Bytes (heap_free_bytes) | Sampled with sys_heap_runtime_stats_get() from _system_heap and reported from free_bytes. |
Heap Allocated Bytes (heap_allocated_bytes) | Sampled with sys_heap_runtime_stats_get() from _system_heap and reported from allocated_bytes. |
CPU Utilization Percent (cpu_utilization_percent) | Sampled with cpu_load_get(true) and converted from per-mille to percent. |
Thread Stack Free Bytes (thread_stack_free_bytes) | Sampled per tracked thread with k_thread_stack_space_get(). |
Thread Stack Used Percent (thread_stack_used_percent) | Derived per tracked thread from thread->stack_info.size and k_thread_stack_space_get(). |
Network TX Bytes (network_tx_bytes) | Sampled per active interface via net_if_foreach(...) from iface->stats.bytes.sent. |
Network RX Bytes (network_rx_bytes) | Sampled per active interface via net_if_foreach(...) from iface->stats.bytes.received. |
MQTT Connection State (connection_mqtt_connected) | Event-driven and reported when MQTT state changes through spotflow_metrics_system_report_connection_state(bool). |
Boot Reset Cause (boot_reset) | Reported once on boot using hwinfo_get_reset_cause(), then reset cause is cleared with hwinfo_clear_reset_cause(). |
By default, stack metrics are collected for all threads (CONFIG_SPOTFLOW_METRICS_SYSTEM_STACK_ALL_THREADS=y).
If you need to limit this, disable that option and register only selected threads with spotflow_metrics_system_enable_thread_stack(...).
Check implementation details in the SDK system metrics folder.
Analyze metrics in dashboards
After enabling system metrics, open the Device Dashboard to inspect device vitals, resource usage, and connectivity trends:
(Optional) Tune collection and aggregation
Use these options to control sampling cadence and the aggregation window before upload:
CONFIG_SPOTFLOW_METRICS_SYSTEM_COLLECTION_INTERVAL=10
CONFIG_SPOTFLOW_METRICS_SYSTEM_AGGREGATION_INTERVAL=60CONFIG_SPOTFLOW_METRICS_SYSTEM_COLLECTION_INTERVALdefines how often metrics are sampled (in seconds).CONFIG_SPOTFLOW_METRICS_SYSTEM_AGGREGATION_INTERVALdefines how long samples are aggregated before sending.- Aggregation interval supports
0(no aggregation),60(1 minute),3600(1 hour), and86400(1 day). - With aggregation interval
0, each sample is sent immediately. - Lower collection interval gives finer time resolution but increases local processing overhead.
- Higher aggregation interval reduces message frequency and network traffic by combining more samples.
Reference repository materials
Learn more
How is this guide?