nRF Cloud Log

This library is an enhancement to the nRF Cloud library. It enables applications to generate and transmit messages that comply with the Logs feature of nRF Cloud. Log messages are compact JSON documents generated directly by an application if the nRF Cloud logging backend is not used. If the nRF Cloud logging backend is enabled, Log messages encapsulate Zephyr Logging output. The logging backend can either use JSON encoding or Dictionary-based Logging encoding.

Overview

This library provides an API for either REST-based or MQTT-based applications to send logs to nRF Cloud. For MQTT-based applications, you can enable or disable logging as well as change the logging level remotely using the nRF Cloud portal or nRF Cloud Patch Device State REST API. For REST-based applications, the enabled state and logging level can be controlled at compile time or at run time on the device, but not from the cloud.

Each JSON log message contains the following elements:

  • appId - Set to LOG.

  • ts - Timestamp if accurate time is known, in the Unix epoch.

  • seq - Sequence number to help order messages sent simultaneously, as well as to sort messages used when no timestamp is available.

  • dom - Logging domain ID; usually 0.

  • src - Name of the C function or subsystem which generated the log.

  • lvl - Log level:

    • 0 = NONE (off)

    • 1 = ERR

    • 2 = WRN

    • 3 = INF

    • 4 = DBG

  • msg - The message string.

The library sets the sequence number and timestamp automatically.

Log messages displayed by a device through a UART or RTT connection show timestamps that reset to 0 when the device resets. Cloud-based log messages show timestamps with real date and time values for when each message was generated. Using real date and time for timestamps is important because log messages are stored by default for up to 30 days.

The nRF Cloud website displays a device’s log messages and enables the user to download historical log messages. Log messages can also be retrieved using the ListMessages REST API.

Supported features

If the Date-Time library is enabled and the current date and time are known, the timestamp field of the log is automatically set accordingly. The sequence number is set to a monotonically-increasing value that resets to 0 when the device restarts.

Supported backends

When so configured, this library includes a Zephyr logging backend that can transport log messages to nRF Cloud using MQTT or REST. The logging backend can also use either JSON messages or dictionary-based compact binary messages.

Multiple JSON log messages are sent together as a JSON array to the d2c/bulk device message topic. The nRF Cloud backend splits the array into individual JSON messages for display. Using the bulk topic reduces the data transfer size as MQTT or REST message overhead is consolidated for multiple messages.

Multiple dictionary-based log messages are sent together as a binary message to the d2c/bin device message topic. The nRF Cloud portal does not display the contents of the dictionary-based log messages in real time. Instead, you must download a binary file containing the logs over a certain range of time, then decode the logs using a Python script and the dictionary built when the application was built.

Requirements

The device must be connected to nRF Cloud before calling the nrf_cloud_log_send() function. The nrf_cloud_rest_log_send() function initiates the connection as needed.

Configuration

Configure one or both of the following Kconfig options to enable direct log messages or the logging backend:

If only the first is enabled:

  • Calls to the direct log message functions nrf_cloud_log_send() and nrf_cloud_rest_log_send() send messages direct to nRF Cloud immediately.

  • The cloud logging backend is not available, and consequently, no Zephyr log messages are transmitted to the cloud.

If only the second is enabled:

  • Only the logging backend is present and all enabled Zephyr log messages of the proper level are sent to the cloud.

  • Direct log message functions are not available.

If both options are enabled, calls to the direct log message functions are passed to the logging backend instead.

Configure one of the following options to select the data transport method:

Configure the message encoding:

See Dictionary-based Logging to learn how dictionary-based logging works, how the dictionary is built, and how to decode the binary log output. Dictionary logs are compact binary log messages that require decoding using an offline script. As such, dictionary logs are up to 60% smaller than JSON logs, but cannot be viewed in the nRF Cloud user interface in real time. Instead, the user interface displays a link from which you can download a single binary file containing the logs. To successfully decode dictionary logs, you must use the log_dictionary.json file built by the build system at the same time as the firmware image. If you modify the source code and build the firmware image again, the log_dictionary.json file may change. Keep track of each firmware image and the log_dictionary.json file when a device runs different firmware images.

Configure the default log level to be sent to the cloud:

For fine run-time control of log levels for each logging source, configure the following:

See Run-time Filtering for more information.

Finally, configure these additional options:

See Configuring your application for information on how to change configuration options.

Usage

To use this library, complete the following steps:

  1. Include the nrf_cloud_log.h file.

  2. If the CONFIG_NRF_CLOUD_LOG_DIRECT Kconfig option is enabled, call the nrf_cloud_log_send() function when connected to nRF Cloud using MQTT or nrf_cloud_rest_log_send() when using REST.

  3. If the CONFIG_NRF_CLOUD_LOG_BACKEND option is enabled, use the normal Zephyr logging macros LOG_ERR, LOG_WRN, LOG_INF, or LOG_DBG, as well as the _HEXDUMP_ forms.

Samples using the library

The following nRF Connect SDK samples use this library:

Limitations

For REST-based applications, you can disable or set a log level for logs only at compile time.

Dependencies

This library uses the following nRF Connect SDK libraries:

API documentation

Header file: include/net/nrf_cloud_log.h
Source files: subsys/net/lib/nrf_cloud/src/nrf_cloud_log.c
Source files: subsys/net/lib/nrf_cloud/src/nrf_cloud_log_backend.c
group nrf_cloud_log

Defines

nrf_cloud_log_send(log_level, fmt, ...)

Functions

void nrf_cloud_log_init(void)

Initialize the nRF Cloud logging subsystem. Call after the date_time library is ready.

void nrf_cloud_log_rest_context_set(struct nrf_cloud_rest_context *ctx, const char *dev_id)

Set REST context for logging subsystem.

Tell REST-based logger the REST context and device_id for later use when outputting a log. This is used by the nRF Cloud logs backend when CONFIG_NRF_CLOUD_LOG_BACKEND=y.

Parameters:

  • ctx – [in] REST context to use.

  • dev_id – [in] Device ID to send message on behalf of.

void nrf_cloud_log_level_set(int level)

Set the logging level.

Set the log level, but do not change whether the nRF Cloud logging backend is enabled.

Log messages with a log level larger than this will not be sent. For example, if log_level is LOG_LEVEL_WRN (2), then LOG_LEVEL_WRN (2) and LOG_LEVEL_ERR (1) messages will be sent, and LOG_LEVEL_INF (3) and LOG_LEVEL_DBG (4) will not. Set log_level to LOG_LEVEL_NONE (0) to disable logging. See zephyr/include/zephyr/logging/log_core.h.

Parameters:

  • level – The log level.

void nrf_cloud_log_enable(bool enable)

Enable or disable logging to the cloud.

When CONFIG_NRF_CLOUD_LOG_BACKEND=y, will enable or disable the log backend, without changing the log level. Disable the log backend to conserve power by eliminating unnecessary processing of log messages.

When CONFIG_NRF_CLOUD_LOG_DIRECT=y, the log enable state determines whether calls to nrf_cloud_log_send() or nrf_cloud_rest_log_send() will succeed. This will conserve power by not transmitting log messages when not needed.

Parameters:

  • enable – [in] Set true to send logs to the cloud, false to disable.

bool nrf_cloud_log_is_enabled(void)

Find out if logger is enabled.

Return values:

True – if logger is enabled.

void nrf_cloud_log_control_set(int log_level)

Control nRF Cloud logging.

Set log level. If the level is set to LOG_LEVEL_NONE, the nRF Cloud logging backend will be disabled, otherwise it will be enabled. This combines the action of nrf_cloud_log_enable() and nrf_cloud_log_level_set().

Parameters:

  • log_level – The log level to go to the cloud.

int nrf_cloud_log_control_get(void)

Get current log level for logging to nRF Cloud.

Return values:

Current – log level.

bool nrf_cloud_is_text_logging_enabled(void)

Determine if build is configured for text (JSON) cloud logging.

Returns:

bool True if build for JSON-based logs. False otherwise.

bool nrf_cloud_is_dict_logging_enabled(void)

Determine if build is configured for dictionary (binary) logging.

Returns:

bool True if build for dictionary logs. False otherwise.