The following FreeRTOS Libraries use this logging functionality:
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.
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:
LogInfo( ( “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
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
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:
#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)
#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:
#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.
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.h file, and for the coreMQTT library in the core_mqtt_config.h file.
Below is an template of using the logging configuration.
#if !defined( LOG_METADATA_FORMAT ) && !defined( LOG_METADATA_ARGS )
#define LOG_METADATA_FORMAT "[%s:%d]"
#define LOG_METADATA_ARGS __FILE__, __LINE__
#define SdkLog( message ) MyLogger message
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.