Migrate legacy nRF Cloud Alerts to Trace Events

Naming disambiguation

This guide covers migrating legacy nRF Cloud SDK Alerts (nrf_cloud_alert_send()) to Trace Events. These are unrelated to platform alerts, which trigger notifications based on fleet-wide metric thresholds.

Migrating from legacy nRF Cloud Alerts to Trace Events expands the monitored data from simple application-level signaling to detailed code-level execution tracking.

Both systems enable devices to report critical issues without halting or rebooting, but Trace Events automatically capture the call site, deduplicate recurring errors into issues, and operate independently of the legacy nRF Cloud transport.

Conceptual comparison

Legacy nRF Cloud Alerts signal predefined application conditions—low battery, temperature threshold, device online/offline. A call to nrf_cloud_alert_send() transmits a compact JSON payload containing a type enum, a float value, an optional description string, and a timestamp. Each alert is independent: it has no deduplication or grouping, and alerts are stored in the legacy nRF Cloud portal for 30 days.

Trace Events track recoverable errors. In addition to a user-defined reason code, each event automatically captures the Program Counter (PC) and Link Register (LR) at the call site—enough for the platform to decode the exact source file, function name, and line number for the topmost two stack frames. Similar events are deduplicated and grouped into issues, and data persists indefinitely.

	Legacy nRF Cloud Alerts	Trace Events
Primary purpose	Application condition signaling	Recoverable error tracking
Data captured	Type enum + float value + string	Reason code + PC + LR (+ optional status or log)
Call-site context	None	Top 2 stack frames decoded to source
Issue grouping	None	Automatic by reason + backtrace
ISR-safe	No	Yes
Retention	30 days in Legacy nRF Cloud portal	Persistent issues in the platform
Transport dependency	MQTT, CoAP, or REST (selected at build time)	Independent of transport

Migration steps

important

Complete the Nordic nRF Connect SDK integration before following this guide.

1. Define your trace reasons

Legacy nRF Cloud Alert types come from the built-in nrf_cloud_alert_type enum or from application-defined integers above ALERT_TYPE_CUSTOM = 100. Replace each one with an entry in memfault_trace_reason_user_config.def (see Trace Events):

// memfault_trace_reason_user_config.def
MEMFAULT_TRACE_REASON_DEFINE(device_online)
MEMFAULT_TRACE_REASON_DEFINE(device_offline)
MEMFAULT_TRACE_REASON_DEFINE(low_battery)
MEMFAULT_TRACE_REASON_DEFINE(high_temperature)
MEMFAULT_TRACE_REASON_DEFINE(high_humidity)
MEMFAULT_TRACE_REASON_DEFINE(shock_detected)

See UI rendering in Trace Events to preview how reason names are displayed in the platform.

2. Replace alert calls with trace macros

Before (Legacy nRF Cloud) uses a dedicated function per transport:

#include <net/nrf_cloud_alert.h>

// MQTT or CoAP transport
nrf_cloud_alert_send(ALERT_TYPE_BATTERY, battery_volts, "Low battery");

// REST transport (separate function, requires context and device ID)
nrf_cloud_rest_alert_send(&rest_ctx, device_id,
                          ALERT_TYPE_BATTERY, battery_volts, "Low battery");

After (Trace Events) uses a single macro regardless of transport:

#include <memfault/core/trace_event.h>

// Captures PC + LR automatically; no struct to populate
MEMFAULT_TRACE_EVENT(low_battery);

// Include the numeric value (replaces the float value field)
MEMFAULT_TRACE_EVENT_WITH_STATUS(low_battery, battery_mv);

// Include a log string (replaces the description field)
MEMFAULT_TRACE_EVENT_WITH_LOG(low_battery, "Battery: %.2fV", battery_volts);

For details on how events are grouped and when to prefer each variant, see Trace event variants in Trace Events.

3. Configure timestamps

Both systems use the Date-Time library for timestamps when it is enabled in your application, so there is no trade-off. If Date-Time is not enabled, legacy nRF Cloud falls back to a sequence number, while Trace Events timestamp events at upload time (which suits frequently connected devices). Trace Events also support alternate on-device time sources such as a hardware RTC. A single Kconfig option selects the source:

# nRF91 Series (uses the Nordic Date-Time library)
CONFIG_MEMFAULT_SYSTEM_TIME_SOURCE_DATETIME=y

# Zephyr projects with a hardware RTC
CONFIG_MEMFAULT_SYSTEM_TIME_SOURCE_RTC=y

For full details, see Event Timestamps.

Syntax mapping

Legacy nRF Cloud alert type	Suggested trace reason	Recommended macro
`ALERT_TYPE_DEVICE_NOW_ONLINE`	`device_online`	`MEMFAULT_TRACE_EVENT(device_online)`
`ALERT_TYPE_DEVICE_NOW_ONLINE_WDT`	`device_online_after_wdt`	`MEMFAULT_TRACE_EVENT(device_online_after_wdt)`
`ALERT_TYPE_DEVICE_GOING_OFFLINE`	`device_offline`	`MEMFAULT_TRACE_EVENT(device_offline)`
`ALERT_TYPE_MSG`	`app_message`	`MEMFAULT_TRACE_EVENT_WITH_LOG(app_message, "%s", desc)`
`ALERT_TYPE_TEMPERATURE`	`high_temperature`	`MEMFAULT_TRACE_EVENT_WITH_STATUS(high_temperature, temp_c)`
`ALERT_TYPE_HUMIDITY`	`high_humidity`	`MEMFAULT_TRACE_EVENT_WITH_STATUS(high_humidity, humidity_pct)`
`ALERT_TYPE_BATTERY`	`low_battery`	`MEMFAULT_TRACE_EVENT_WITH_STATUS(low_battery, battery_mv)`
`ALERT_TYPE_SHOCK`	`shock_detected`	`MEMFAULT_TRACE_EVENT_WITH_STATUS(shock_detected, accel_ms2)`
`ALERT_TYPE_CUSTOM + N`	(define your own)	`MEMFAULT_TRACE_EVENT(your_custom_reason)`

Complete before/after example

// BEFORE: Legacy nRF Cloud Alert
#include <net/nrf_cloud_alert.h>

void battery_monitor_check(float voltage_v)
{
    if (voltage_v < BATTERY_LOW_THRESHOLD_V) {
        nrf_cloud_alert_send(ALERT_TYPE_BATTERY, voltage_v, "Low battery");
    }
}

// AFTER: Trace Event
#include <memfault/core/trace_event.h>

// In memfault_trace_reason_user_config.def:
//   MEMFAULT_TRACE_REASON_DEFINE(low_battery)

void battery_monitor_check(int voltage_mv)
{
    if (voltage_mv < BATTERY_LOW_THRESHOLD_MV) {
        MEMFAULT_TRACE_EVENT_WITH_STATUS(low_battery, voltage_mv);
    }
}

Recommended alternatives

Trace events are not the only migration target. Depending on your use case, the following features may fit better.

Device messages

Use device messages to send application data to the platform and to monitor device behavior, debug issues, and collect operational data. For more information, see Device messages.

Device metrics

Use device metrics to track key performance indicators (KPIs) and monitor fleet-wide trends. Metrics help you understand device health and usage patterns. For more information, see Metric Configuration.

Additional alerting features

The platform web application provides additional alerting features:

Fleet-wide alerts – Set thresholds for metrics and receive notifications when the thresholds are exceeded.
Device-specific alerts – Monitor individual devices for specific conditions.

For more information, see Alerts.

Migration workflow

Review the alerts and logs currently in use.
Determine whether device messages, metrics, or trace events fit each use case.
Update your device firmware to use the new libraries and APIs.
Verify that the new setup works as expected and provides the required insights.

Get help

If you have questions about the migration, you can contact us for assistance.

Conceptual comparison​

Migration steps​

1. Define your trace reasons​

2. Replace alert calls with trace macros​

3. Configure timestamps​

Syntax mapping​

Complete before/after example​

Recommended alternatives​

Device messages​

Device metrics​

Additional alerting features​

Migration workflow​

Get help​