Logging

Ariel OS supports logging on all platforms and it is enabled by default with the logging laze module. Logging offers a set of macros that print on the debug console with helpful logging formatting.

Printing Panics

Panics are automatically printed on the logging output. If this is unwanted, the panic-printing laze module can be disabled.

Logging

Within Rust code, import ariel_os::log items, then use Ariel OS logging macros:

use ariel_os::log::info;

#[ariel_os::task(autostart)]
async fn main() {
    info!("Hello!");
}

Filtering Logs

In Ariel OS, the log level defaults to info. It can be configured using the laze variable LOG. Depending on the logger, it may be possible to configure different levels per crate or per module.

Example:

$ laze build -C examples/log --builders nrf52840dk -DLOG=info run

Logging Facades and Loggers

Ariel OS supports multiple logging facades and loggers. Only one of them may be enabled at a time; if none of them are enabled, logging statements become no-operations. Enabling either the defmt or log laze modules allows selecting which logging facade and logger is used. defmt should be preferred when possible as it results in smaller binaries.

Tip

The defmt laze module is favored and enabled by default when possible for the target. Applications that specifically depend on it still need to explicitly select it to make the dependency explicit and increase robustness to potential future changes.

The precise set of formatting operations and traits required on formatted data depends on the selected backend. There are some wrapper structs available in the ariel_os::log module that help represent some types in a portable way; in particular, this includes Debug2Format and Display2Format, which (while defeating some of defmt’s optimizations) come in handy when debugging third party types.

defmt

See the defmt documentation for general info on the defmt’s facade and logger.

The defmt logger supports configuring the log level per crate and per module, as follows:

$ laze build -C examples/log --builders nrf52840dk -DLOG=info,ariel_os_rt=trace run

log

Ariel OS’s logger for log supports configuring the log level globally, but does not currently support per-crate filtering.

Logging Transports

Logging can use various transports, but currently only one can be used at a time. The table below presents those supported in Ariel OS and which hardware and host tool are required:

On ESP32 devices, Ariel OS uses espflash by default to obtain and print logs, whose usage is determined by the espflash laze module. When espflash is selected at the time of compilation, logging-over-debug-channel is not enabled and one of the other available logging transports is used instead.

Important

When using defmt as logging facade, a defmt-enabled host tool must be used so that logs are rendered correctly, as defmt uses its own encoding on the wire. probe-rs and espflash both support defmt’s encoding transparently.

When a separate serial monitor is needed, defmt-print can be used as defmt-enabled serial monitor. If this is not possible, defmt should be disabled and log used instead as logging facade.

Tip

When a logging transport other than the debug channel is enabled, logging can still be used when the debug channel is disabled either in software (by disabling the logging-over-debug-channel laze module) or in hardware when the debug interface itself is disabled. This means that logging can still be used in production, even if the debug interface has been disabled.

If this is unwanted, logging can be disabled altogether by disabling the logging laze module.

Note

Future plans for logging facilities:

• Other logging transports will later be supported, including UART and USB CDC-ACM on non-ESP32 devices.
• Using multiple transports at the same time may be supported in the future.

Fetching and Displaying the Logging Output on the Host

When the flashing transport allows it, the run laze task not only flashes the board but also fetches and displays the logging output on the host. In addition, the attach laze task is available to fetch and display the logging output from an already-flashed, running target. Both the run and attach tasks may be terminated by the target when using semihosting.

The available laze tasks are summarized in the following table:

When multiple tasks of the same name exist, which variant is used depends on which host tool is enabled through its associated laze module (e.g., probe-rs or espflash).

Note

Depending on the logging transport and on the debug channel transport used (if used as logging transport), the attach task may display some logs that have been issued before the task was started: this may happen when the transport uses internal buffers that are only emptied when fetched by a host tool (e.g., RTT).

Tip

It is possible to flash the board using one host tool, before switching to another one to fetch and display the logging output (e.g., in production).