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()
- 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/
SdkLog()
Note the header file ordering in the code snippet at the end of this page.
Defining the SdkLog macro
The
logging_stack.h
logging_stack.h
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/
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
demo_config.h
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.h
file, and for the coreMQTT library in
the core_mqtt_config.h
file.
Below is an template of using the logging configuration.
1/**************************************************/2/******* DO NOT CHANGE the following order ********/3/**************************************************/45/* Include logging header files and define logging configurations in the6 * following order:7 * 1. Include the header file "logging_levels.h".8 * 2. Define the logging configurations for your application. It is required9 * to define LIBRARY_LOG_NAME, LIBRARY_LOG_LEVEL and SdkLog macros.10 * 3. Include the header file "logging_stack.h".11 */1213#include "logging_levels.h"1415/* Logging configurations for the application. */1617/* Set the application log name. */18#ifndef LIBRARY_LOG_NAME19 #define LIBRARY_LOG_NAME "MyApplication"20#endif2122/* Set the logging verbosity level. */23#ifndef LIBRARY_LOG_LEVEL24 #define LIBRARY_LOG_LEVEL LOG_INFO25#endif2627/* 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#endif3334/* Define the platform-specific logging function to call from35 * enabled logging macros. */36#ifndef SdkLog37 #define SdkLog( message ) MyLogger message38#endif3940/************ End of logging configuration ****************/