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.
Install Spotflow Device Module
As the very first step, check one of the following basic integration guides:
Enable metrics in Kconfig
Add the following options to your prj.conf:
CONFIG_SPOTFLOW=y
CONFIG_SPOTFLOW_DEVICE_ID="zephyr-device-001"
CONFIG_SPOTFLOW_INGEST_KEY="{your-ingest-key}"
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?