Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

LibrariesinsideFreeRTOS core

Updated Jul 2025

Logging Functionality

The following FreeRTOS Libraries use this logging functionality:

Logging Macros

The FreeRTOS libraries use the following 4 logging macros, listed in increasing order of verbosity. For example, LogError() is only called when there is an error so is the least verbose, whereas 

LogDebug()
is called more frequently to provide debug level information and is therefore the most verbose.

  • LogError
  • LogWarn
  • LogInfo
  • LogDebug

Logging macros are used with a variable number of arguments, just like printf() (with the exception that they use double parenthesis). For example, the libraries call the logging macros in the following way:

1LogInfo( ( “This prints an integer %d”, 100 ) );

You do not need to define the four logging macros individually. By including the 

FreeRTOS-Plus/Source/Utilities/logging/
logging_stack.h header file you can instead define a single macro called 
SdkLog()
, which will then be applied to all four verbosity levels. When this is done, the verbosity level is set separately by the definition of LIBRARY_LOG_LEVEL, as described below.

Note the header file ordering in the code snippet at the end of this page.

Defining the SdkLog macro

The 

logging_stack.h
header file should be included and the logging configuration macros should be defined within the configuration file of the library in use. For example, to obtain log output from the coreMQTT library, include 
logging_stack.h
and define the logging macros in 
core_mqtt_config.h
.

To obtain logging SkdLog() must be defined to call a thread safe platform specific print function. For example, the print function may output characters to a serial port, or to a TCP socket. As the logging macros accept a variable number of parameters and are used just like printf(), the platform specific print function must have the same prototype (parameters list) as printf(). For example, if your application has a thread safe version of printf() that writes to a serial port you can define SdkLog as:

1#define SdkLog( X ) printf X

Logging macros left undefined are defaulted to be empty macros that do not generate any code.

NOTE: If you don’t use the logging utility headers in FreeRTOS-Plus/Source/Utilities/logging/external_link you can define the four logging macros individually for the logging levels you want by defining the macros in your application - but that is not the recommended method as doing so will prevent LIBRARY_LOG_LEVEL and LIBRARY_LOG_NAME from having any effect.

Setting the Verbosity Level

To set the verbosity level define the LIBRARY_LOG_LEVEL macro to one of the following values in the same configuration file used to define SdkLog(). Valid values for LIBRARY_LOG_LEVEL are:

  • LOG_NONE (turns logging off)
  • LOG_ERROR
  • LOG_WARN
  • LOG_INFO
  • LOG_DEBUG

For example:

1#define LIBRARY_LOG_LEVEL  LOG_NONE

Setting the Text Name

To set the text name define the LIBRARY_LOG_NAME macro to a string within the same configuration file used to define SdkLog(). Each log message prints the name, so it is normal to set the name to the name of the library. For example:

1#define LIBRARY_LOG_NAME “MQTT”

Setting the name to an empty string will save program space.

Setting the Metadata in logs

To add metadata in log messages (like source code location of log messages), the LOG_METADATA_FORMAT and LOG_METADATA_ARGS macros can be defined. The LOG_METADATA_FORMAT macro should be defined to specify the metadata format string, whereas the LOG_METADATA_ARGS macro should be defined to pass the metadata arguments for the format string. Both these macros are prefixed in the log messages passed to the platform specific print function defined for the SdkLog macro.

For example, the following definitions add the function name and line number file of the source file that emits the log message.

  • #define LOG_METADATA_FORMAT “[%s:%d]”
  • #define LOG_METADATA_ARGS __FUNCTION__, __LINE__

Setting the metadata macros to empty values will save program space.

Reference Examples

Notice in the examples links and the template code below that there are 

#ifndef
guards around the logging macro definitions. These are there to avoid multiple definition of the same macro in translation units that include multiple config files. (For example, the MutualAuthMQTTExample.c, includes the 
demo_config.h
through direct inclusion and core_mqtt_config.h through indirect inclusion of core_mqtt.h. For such cases in application code, it is IMPORTANT to include the config file that contains logging configuration for the affected translation unit file at top of the file (i.e. before other header includes) so that the correct configurations are applied.

For an examples in FreeRTOS codebase for logging configuration, refer to the MQTT over TLS Mutual Authentication demo which configures logging for the demo application task (defined in MutualAuthMQTTExample.c) in the demo_config.hexternal_link file, and for the coreMQTT library in the core_mqtt_config.hexternal_link file.

Below is an template of using the logging configuration.

1/**************************************************/
2/******* DO NOT CHANGE the following order ********/
3/**************************************************/
4

5/* Include logging header files and define logging configurations in the
6 * following order:
7 * 1. Include the header file "logging_levels.h".
8 * 2. Define the logging configurations for your application. It is required
9 * to define LIBRARY_LOG_NAME, LIBRARY_LOG_LEVEL and SdkLog macros.
10 * 3. Include the header file "logging_stack.h".
11 */
12

13#include "logging_levels.h"
14

15/* Logging configurations for the application. */
16

17/* Set the application log name. */
18#ifndef LIBRARY_LOG_NAME
19    #define LIBRARY_LOG_NAME "MyApplication"
20#endif
21

22/* Set the logging verbosity level. */
23#ifndef LIBRARY_LOG_LEVEL
24    #define LIBRARY_LOG_LEVEL LOG_INFO
25#endif
26

27/* Define the metadata information to add in each log.
28 * The example here sets the metadata to [:]. */
29#if !defined( LOG_METADATA_FORMAT ) && !defined( LOG_METADATA_ARGS )
30    #define LOG_METADATA_FORMAT "[%s:%d]"
31    #define LOG_METADATA_ARGS __FILE__, __LINE__
32#endif
33

34/* Define the platform-specific logging function to call from
35 * enabled logging macros. */
36#ifndef SdkLog
37    #define SdkLog( message )   MyLogger message
38#endif
39

40/************ End of logging configuration ****************/